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Series Introduction 





This book is a part of a series of books designed to get programmers 
the information they need in a quick and efficient manner. 
Programmers don’t have time to hunt through huge unwieldy manu- 
als trying to find the little piece of information they need to finish 
their tasks. To that end, the design of these books has been optimized 
by programmers for programmers. 

All APIs have been organized into logical groups rather than al- 
phabetically, so, you will find all of the APIs relating to semaphores 
grouped together in one chapter, for example. The reasoning for this 
is clear: A programmer looking up how to create a semaphore will 
most likely want to know how to request it, release it, and so on, im- 
mediately afterward. 

In addition to grouping related APIs, any information that relates 
to that group is provided in the same chapter. Each chapter is prefixed 
with a quick summary of the system architecture related to those APIs, 
and suffixed with any related structures. In some cases, other related 
information may be found in the back of the chapter as well. 

The architecture summaries at the beginning of the chapters are 
designed to provide the programmer a quick overview or, in some cases, 
a refresher on the topic in just a few minutes. I recommend that pro- 
grammers take the time to read these overviews before delving into de- 
sign and coding since so many problems arise from poor initial design 
resulting from a lack of knowledge of the architecture of the topic. 

The API pages were designed primarily for efficiency. Therefore, 
each book in this series may have some small differences on the pages 
containing the actual APIs. For example, the Workplace Shell reference 
does not contain any references to what “INCL_” to define for a given 
API since there is only one for the entire set of Workplace Shell APIs. 

It is my sincere hope that you will find the books in this series the 
quickest, most informative, best organized programmers’ reference 
books you have ever used. 


Marc Stock 


Preface 





This book, like the others in the series, is designed for speedy access to 
thorough information. There are, however, a couple of things missing 
from what you would expect in a control program reference. In short, 
there is no coverage of DosDebug or DosDevIOCtl and their functions. 
I did not cover these APIs because I felt they didn’t fit the scope of this 
book, which encompasses 95 percent of OS/2 programmers. I also did- 
n’t want this book to turn into a huge mega-reference in which you can 
never find what you are looking for because the book is too unwieldy 
and vast. For coverage of DosDebug and DosDevIOCtl, I recommend 
you use the IBM OS/2 2.0 Technical Library—Control Program Reference. 
This book has one other shortfall—no examples. I wanted to write ex- 
amples that were useful, and used the APIs in context together. This re- 
quired a lot of additional work that I could not complete in time for 
publication. Instead, I will make examples available through the 
OS2DF1 Base APIs section library on CompuServe as soon as I com- 
plete them. 

I spent more time researching the subjects that people tend to 
have the most trouble with—like named pipes and EAs. There are nu- 
merous behaviors to both of these topics that are either incorrectly 
documented or not documented at all (as of the time of this writing). 
I also spent a great deal of time determining system limits, such as how 
many timers can be started, how many queues, and so forth. I obtained 
the information via extensive testing and from information I obtained 
from others. As my testing progressed, I found many pieces of infor- 
mation that neither I, nor most other people, were aware of. And while 
the book is done, I feel I could go on forever finding more hidden 
gems in the Control Program APIs. For now, I’ll just have to leave them 
to a second edition.... 


Marc Stock 
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How to Use This Book 





This book is designed as a combination guide and reference, with the 
emphasis on reference. If you are not familiar with the architecture of 
a particular topic, I recommend that you read the architecture sum- 
maries found at the beginning of every chapter. They are short and to 
the point, but they can be very useful for improving your understand- 
ing of the “big picture” or as a quick refresher on an operating system 
feature you used long ago. The summaries also include a section that 
discusses related system limitations, warnings, and the list of APIs be- 
longing to that section. 

If you are familiar with a particular topic and just need to go toa 
specific API, the APIs can be found either by looking them up alpha- 
betically in the chapter to which they belong, or from the API index 
provided in the back. If you don’t know to which topic the API be- 
longs, go to the index. 

Each API includes a prototype of the call. The data types are in 
boldface to help guide the eye when trying to determine which types 
need to be passed. In the parameters section of each call, the parame- 
ter name is shown in boldface/italics to aid in quick location of the pa- 
rameter you are looking for. Note: The prototypes shown in this book 
are for the C interfaces that are included with the OS/2 Toolkit. Ifyou 
are using C++, you will find that a few of the parameter types are a lit- 
tle different from the ones shown in this reference. The Toolkit head- 
ers for C++ use a new type called PCSZ for pointers to null-terminated 
constants. 

Each API also includes an Other Info section which contains mis- 
cellaneous information needed for doing everything from determin- 
ing which #define is required to include the API’s prototype, to which 
DLL contains the code for that API. Here is an example of an Other 
Info section: 


OTHER INFO 
Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 257 DLL: DOSCALLS 
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The Include listed contains the function prototype for the call and 
any related #defines, structures, and more. Do not include this file at 
the beginning of you code. This information is provided purely for ref- 
erence purposes. You will also find the name of the #define that should 
be included to cause the C preprocessor to pull in the necessary func- 
tion prototypes and #defines so that the compiler will not complain. 

Each API also includes a See Also section that includes the names 
of related APIs that might be of interest. ‘This section includes not only 
APIs found in this book, but APIs that are a part of Presentation 
Manager (PM) or the C standard libraries. ‘The calls that are not in this 
book are shown in italics. For example: 


SEE ALSO 


DosCreateNPipe -235, DosDupHandle -221, DosOpen -223, 
DosResetBuffer -247, fclose 


Following the See Also section, the Notes section contains any re- 
lated information that may be important to the use of the API. This 
may be anything from additional details to side-effects. If there is a par- 
ticular side-effect to an API that is possibly destructive or difficult to de- 
tect, then there will also be a Warnings section found after the Notes 
section. I recommend that the warnings be read every time, even if you 
intended to look up only the function prototype. 

And finally, the Data Structures section found in the back of each 
chapter contains the definitions for each structure used with the corre- 
sponding topic’s APIs. The numbers on the right indicate the offset, in 
bytes, from the beginning of the structure with the total size, in bytes, at 
the top of the structure. At the end of each structure definition there is 
a list itemizing which APIs use the structure so that structures can be 
cross-referenced from API to structure, and from structure to API. 
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Device 
nput/Output 





n OS/2, communication with devices can be performed with both 

high-level and low-level interfaces. The high-level interfaces are APIs 
like DosOpen, DosRead, and DosWrite. These allow the programmer 
to perform input/output (I/O) on a device with the familiar file sys- 
tem stream interface. Typically, the high-level interfaces are sufficient 
for most device I/O. The low-level interface for communicating with a 
device through a device driver is DosDevIOCtl. Additionally, applica- 
tions can determine which devices are attached by calling DosDev- 
Config; DosPhysicalDisk will return information on _ partitionable 
disks, and DosBeep will generate sound on the computer speaker. 


I/O Control Interface 


DosDevIOCtl is an expandable I/O control facility that sends com- 
mands and data to and from device drivers. The kernel takes generic 
I/O control packets and reformats them into request packets, and 
then calls the device driver. The device driver then performs the re- 
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quested action. DosDevIOCtl can be used with either character or 
block devices, but before it can be used, a device handle must be ob- 
tained by calling DosOpen. 

The DosDevIOCtl API is broken up into numerous categories. 
Each category represents a different device. For example, IOCTL_ 
ASYNC represents the COM port. Within each category are several 
functions that may be performed specific to that category, like setting 
the COM port baud rate. The various categories and functions of 
DosDevIOCtl are documented in IBM’s OS/2 2.0 Control Program 
Reference. 





DosBeep generates a specific frequency on the computer speaker 
(pg. 2). 

DosDevConfig queries information about attached devices (pg. 3). 
DosDevIOCtl performs low-level I/O on a device driver via a device 
handle (pg. 4). 

DosPhysicalDisk returns information on partitionable disks (pg. 6). 





DosBeep Device I/O 


Generates a specified frequency on the computer speaker. 


SYNTAX 
APIRET DosBeep(ULONG u/lFrequency, ULONG ulDuration) 


PARAMETERS 

ulFrequency - input 

The frequency, in Hertz (37 - 32767). 
ulDuration - input 

The duration of the sound, in milliseconds. 


RETURNS 
0 NO_ERROR 395 ERROR_INVALID_FREQUENCY 
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OTHER INFO 

Include file: bsedos.h Define: DOS PROCESS 
Ordinal: 286 DLL: DOSCALLS 
SEE ALSO 

DosDevIOCtl -4 

NOTES 

None 

DosDevConfig Device I/O 


Returns information about attached devices. 


SYNTAX 
APIRET DosDevConfig(PVOID pDevicelnfo, ULONG wulDevType) 


PARAMETERS 

pDevicelnfo - output 

The address of a buffer that will hold the returned information. 
Currently, all information returned requires | byte. 

ulDevType - input 

The type of information to return. Specify one of the following: 


Constant Description 
DEVINFO_PRINTER Q The number of attached printers. 
DEVINFO_RS232 1 The number of RS232 ports. 
DEVINFO_FLOPPY 2 The number of diskette drives. 


DEVINFO_COPROCESSOR 3 The presence of a math coprocessor 
hardware. 0 = no coprocessor, 
1 = coprocessor exists. 


DEVINFO_SUBMODEL 4 The system submodel byte. 
DEVINFO_MODEL 5 The system model byte. 
DEVINFO_ADAPTER 6 The type of primary display adapter. 


0 = monochrome, | = other. 
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RETURNS 
0 NO_ERROR 87 ERROR_INVALID_PARAMETER 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSPROCESS 
Ordinal: 231 DLL: DOSCALLS 


SEE ALSO 
DosBeep -2, DosDevIOCtl -4, DosPhysicalDisk -6 


NOTES 


None 





DosDevliOCtl Device I/O 





Performs I/O control functions on a device via a device handle. 


SYNTAX 


APIRET DosDevIOCtl(HFILE h/Device, ULONG wulCategory, ULONG 
ulFunction, PVOID pParmList, VLONG ulParm- 
LenMax, PULONG pulParmLenInOut, PVOID 
pDataArea, ULONG ulDataLenMax, PULONG 


pulDataLenInOut) 
PARAMETERS 
hfDevice - input 
The handle of the device. 


ulCategory - input 

The category number (0 - 255). 

ulFunction - input 

The function of the category to perform (0 - 255). 

pParmList - input/output 

On input, the address of a command-specific argument list. A null in- 
dicates this parameter is not defined for this function. 

ulParmLenMax - input 

The maximum length of data to return to the buffer pointed to by 
pParmList, in bytes. 

pulParmLenInOut - input/output 
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On input, the address of a ULONG containing the length, in bytes, of 
the parameter list pointed to by pParmList. On output, the address of a 
ULONG containing the length, in bytes, of the data returned to the 
buffer pointed to by pParmLust. If the call returns, ERROR_BUFFER_ 
OVERFLOW, then this value will point to the size of the buffer neces- 
sary to hold the data, and no data will be returned. 

pDataArea - input/output 

On input, the address of the data area. A null indicates this parameter 
is not defined for this function. 

ulDataLenMax - input 

The maximum length of data to return to the buffer pointed to by 
pDataArea, in bytes. 

pulDataLenInOut - input/output 

On input, the address of a ULONG containing the length, in bytes, of 
the data area pointed to by pDataArea. On output, the address of a 
ULONG containing the length, in bytes, of the data returned to the 
buffer pointed to by pDataArea. If the call returns, ERROR_BUFFER_ 
OVERFLOW, then this value will point to the size of the buffer neces- 
sary to hold the data, and no data will be returned. 


RETURNS 
0 NO_ERROR 111 ERROR BUFFER OVERFLOW 
1 ERROR INVALID _ 115 ERROR _ PROTECTION _ 
FUNCTION VIOLATION 
6 ERROR_ INVALID _ 117 ERROR INVALID CATEGORY 
HANDLE 
15 ERROR INVALID _ 119 ERROR BAD_ DRIVER LABEL 
DRIVE 
31 ERROR GEN __ 163 ERROR UNCERTAIN. MEDIA 
FAILURE 
87 ERROR INVALID _ 165 ERROR MONITORS _ NOT. 
PARAMETER SUPPORTED 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSDEVICES 
Ordinal: 284 DLL: DOSCALLS 
SEE ALSO 


DosBeep -2, DosDevConfig -3, DosPhysicalDisk -6 
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NOTES 


You cannot pass a non-null pointer with a zero length. 

Values returned in the range OxFF00 through OxFFFF are user-de- 
pendent error codes, and values returned in the range OxFEO00 
through OxFEFF are device driver-dependent error codes. 

Refer to the IBM OS/2 2.0 Control Program Reference for infor- 
mation on the IOCtl categories and functions. 





DosPhysicalDisk Device I/O 


Returns information on partitionable drives. 


SYNTAX 


APIRET DosPhysicalDisk (ULONG ulFunction, PVOID pDataPt, 
ULONG wlDataLen, PVOID pParmPtr, 
ULONG wlParmLen) 


PARAMETERS 
ulFunction - input 
Specify one of the following functions to perform: 


Constant Description 


INFO_COUNT_PARTIONABLE_DISKS 1 Return the total number of 
partitionable disks. Specify no 
parameters. Returns 2 bytes in 
pDataPtr. 


INFO_GETIOCTLHANDLE 2 Return a handle that can be 
used with Category 9 IOCtls. 
Specify the following string: n:, 
where n is the 1-based 
partitionable disk number. 
Returns 2 bytes in pDataPir. 


INFO_FREEIOCTLHANDLE 3 Frees a partitionable disk 
handle. pDataPir must be zero. 





pDataPtr - output 

The address of a buffer where information will be feted: 
ulDataLen - input 

The size, in bytes, of the data pointed to by pDataPtr. 
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pParmPtr - input 

The address of a buffer containing the input parameters for the func- 
tion. 

ulParmLen - input 

The length, in bytes, of the parameters pointed to by pParmPtr. 


RETURNS 


0 NO_ERROR 87 ERROR_INVALID_PARAMETER 
1 ERROR_INVALID_ FUNCTION 


OTHER INFO 


Include file: bsedos.h Define: INCL _DOSPROCESS 
Ordinal: 287 DLL: DOSCALLS 


SEE ALSO 
DosBeep -2, DosDevConfig -3, DosDevIOCtl -4 


NOTES 


The handle returned can only be used with Category 9 DosDevIOCtl 
functions. 





Dynamic Linking 
and Resources 


Often, large applications are broken up into several smaller applica- 
tions for modularity, safety, and to reduce RAM requirements. Most of 
the time there are several routines that are useful to some or all of the 
applications. Dynamic link libraries (DDLs) allow programmers to 
combine a collection of routines and data resources so that they may 
be accessed by several executables (or even other DLLs) simultane- 
ously. The primary benefits of DLLs are as follows: 


@ The internal nature of the routines can be kept secret from the ap- 
plications. Only the interfaces for the routines need to be provided 
to use them. 

@ Regardless of the number of applications that are linked to the same 
DLL, the code is only loaded once. The data segments, by default, 
are not shared. 

@ DLLs can have shared data segments defined, thereby giving them a 
built-in form of interprocess communication (IPC). 

® Functions in DLLs can be updated and added without requiring ex- 
ecutables that use them to be relinked if they use name lookup or 
the ordinals are not changed. 
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@ Language support for executables can be easily managed by placing 
all string and dialog resources into a DLL. These resources can then 
be translated into different languages which are then built into new 
DLLs. The country-specific DLL can then be shipped with the exe- 
cutable. ‘The executable does not need to be relinked. 


Static Linking DLLs 


The interfaces of a DLL typically consist of two parts: the header file 
that contains the function prototypes for the routines in the DLL, and 
an import library file (.LIB) that contains the locations of all of the en- 
try points for the functions. The import library is then specified as one 
of the libraries in the library parameter of LINK386. This method of 
linking to a DLL is referred to as static (or loadtime) linking, since the 
locations of the entry points are built into the executable which are 
then resolved at loadtime. Normally, an application must explicitly im- 
port a function in its module definitions file before it can be used; 
however, when using import libraries, the client application does not 
need to explicitly import the routines since the import library will do 
that automatically. DLLs that are linked to statically must be in the LIB- 
PATH at the time the executable is loaded, otherwise the system will 
cease loading the application. 


Dynamically Linking to DLLs 


DLLs can be linked to dynamically as well (referred to as dynamic or 
runtime linking) by using DosLoadModule. Function addresses are 
then obtained by calling DosQueryProcAddr. If the DLL is not avail- 
able, you can then conserve memory and keep your programs free of 
bindings that could keep your program from running. The cost of this 
flexibility is performance when you are dynamically linking to func- 
tions that are frequently used. However, if you are designing software 
for memory-constrained systems you could, in fact, improve your per- 
formance by keeping the number of loaded code segments to a mini- 
mum, thereby reducing memory swapping. 


Performance Issues 


DLL load time and working set size can be reduced by combining 
many DLLs into a few DLLs, and by organizing like functions together 
in the source code. Combining like functions helps keep those func- 
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tions within the same page or span of pages, which in turn helps re- 
duce swapping. Specifying LOADONCALL for code or data segments 
in the module definitions file of a DLL will not affect the performance 
of a DLL, since all code and data segments are loaded on demand re- 
gardless of the PRELOAD/LOADONCALL setting. DLLs with numer- 
ous exports will load quicker if the exports are resolved via ordinal 
rather than by name. Ordinals are assigned to exports via the EX- 
PORTS keyword in the module definition file. Running IMPLIB 
against the DLL rather than the DEF file will cause the loader to load 
the file via ordinal, and not load the function via name lookup (which 
saves RAM). 


DLL Initialization 


Currently, DLL initialization routines are called from the last DLL 
loaded to the first DLL loaded; however, different versions of OS/2 
may invoke the initialization routines in different orders. ‘Therefore, 
no dependencies should be made in relation to the order of invoca- 
tion of initialization routines. The loader loads linked DLLs until all 
imports are resolved or until a DLL is dependent on a DLL that is al- 
ready loaded. No DLL initialization routines are invoked until all of 
the linked DLLs have been successfully loaded by the loader. 


Querying DLLs 


The functions that are contained in a DLL may be queried to determine 
if they are 16- or 32-bit by calling DosQueryProcType. Executables, 
DLLs, and device drivers can be identified using DosQueryAppType. 
This API is also useful for testing whether an executable, DLL, or de- 
vice driver exists and whether it is corrupted. DosQueryModule- 
Handle can be used to obtain the module handle of a previously 
loaded DLL, and is often used to determine if a DLL has already been 
loaded. 

DosGetResource may be used to retrieve resource objects such as 
string tables and menus by their resource IDs. However, there are sev- 
eral Presentation Manager APIs that make loading and using these re- 
sources much easier. Look for Presentation Manager APIs that begin 
with WinLoad. 
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Unloading DLLs 


DLLs may be unloaded by calling DosFreeModule. However, a DLL 
may not be unloaded if it contains any routines that are part of an exit 
list. To unload the DLL, the exit list routines that are in the DLL must 
be deregistered (see DosExitList, pg. 264). There is also a problem 
when unloading 16-bit DLLs that include STDIO library routines that 
are compiled with the 16-bit Microsoft compiler: The compiler inserts 
an exit list routine into the code and, therefore, keeps it from ever be- 
ing unloaded. 


Dynamic Code Linking Functions 





DosFreeModule frees the reference to the dynamic link library for the 
calling process (pg. 11). 

DosLoadModule loads a dynamic link library and returns a handle for 
the library (pg. 12). 

DosQueryAppType returns whether the target file is an executable, 
DLL, or device driver (pg. 14). 

DosQueryModuleHandle returns the handle of a previously loaded dy- 
namic link library (pg. 17). 

DosQueryModuleName gets the fully qualfied pathname of a dynamic 
link library (pg. 17). 

DosQueryProcAddr returns the address of the specified procedure 
within a dynamic link library (pg. 18). 

DosQueryProcType returns whether the specified procedure is 16- or 
32-bit (pg. 20). 





@ DosFreeModule Dynamic Linking 


Releases access to a DLL, previously loaded using DosLoadModule, for 
the calling process. 


SYNTAX 
APIRET DosFreeModule(HMODULE hmodLibrary) 
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PARAMETERS 


hmodLibrary - input 
The module handle of the DLL to be freed. 


RETURNS 

0 ON_ERROR 12 ERROR _ INVALID ACCESS 
6 ERROR INVALID HANDLE 95 ERROR INTERRUPT 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSMODULEMGR 
Ordinal: 322 DLL: DOSCALLS 

SEE ALSO 


DosLoadModule -12, DosQueryModuleName -17, _ freemod 


NOTES 


DosFreeModule frees the reference to the dynamic link library for the 
current process. Once the last reference to the DLL is released, the 
module is freed from memory. 

ERROR _ INVALID ACCESS is returned if the module to be freed 
was not loaded using DosLoadModule. 


RESTRICTIONS/WARNINGS 


@ After this function has completed, the module handle is no longer 
valid and may not be used to refer to the DLL. An attempt to invoke 
any procedures loaded from that DLL will result in a protection 
fault. 

Even if the DLL is no longer linked to by any processes, it will stay 
loaded if it contains routines that are part of an exit list for any 
linked program. In this case, DosExitList must be called to remove 
the routines. Typically, an ERROR_INVALID_ ACCESS error is re- 
turned in this case. In some versions of Microsoft C (16-bit) and 
C/2, an exit list routine would be registered under the covers when 
any STDIO routines were used, and this would make it impossible to 
dynamically unload the module. 





DosLoadModule Dynamic Linking 


Loads a dynamic link library (DLL), and returns its module handle. 


SYNTAX 
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APIRET DosLoadModule(PSZ pszObjectNameBuf, ULONG ulObjName- 
BufLen, PSZ pszModuleName, PHMODULE 
pModuleHandle) 


PARAMETERS 
pszObjectNameBuf - input/output 


The address of a buffer that will, upon failure, contain the name of the 
procedure or DLL that caused the call to fail. 


ulObjNameBufLen - input 


The size, in bytes, of the buffer pointed to by pszObjectNameBuf. 


pszModuleName - input 


A null-terminated string that contains the fully qualified path of the 
DLL to load. To load a DLL from the LIBPATH, specify the file name 


of the DLL with no extension. 
pModuleHandle - output 


The address of an HMODULE to receive the module handle of the 


DLL. 


RETURNS 
0 NO_ERROR 


2 ERROR_FILE_NOT_ 
FOUND 

3 ERROR_PATH_NOT_ 
FOUND 

4 ERROR_TOO_MANY_ 
OPEN_FILES 

5 ERROR_ACCESS_ DENIED 


8 ERROR_NOT_ 
ENOUGH_MEMORY 
11 ERROR_BAD_ FORMAT 


26 ERROR_NOT_DOS_DISK 


32 ERROR_SHARING _ 
VIOLATION 

33 ERROR_LOCK_VIOLATION 

36 ERROR_SHARING_ 
BUFFER_EXCEEDED 


127 ERROR_PROC_NOT_ 
FOUND 
180 ERROR_INVALID_ 
SEGMENT NUMBER 
182 ERROR_INVALID_ 
ORDINAL 
190 ERROR_INVALID_ 
MODULETYPE 
191 ERROR_INVALID_ 
EXE_SIGNATURE 
192 ERROR_EXE_ MARKED _ 
INVALID 
194 ERROR _ITERATED_ 
DATA_EXCEEDS_64K 
195 ERROR_INVALID_ 
MINALLOCSIZE 
196 ERROR_DYNLINK_ 
FROM_INVALID_RING 
198 ERROR_INVALID_ SEGDPL 
199 ERROR_AUTODATASEG _ 
EXCEEDS_64K 
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95 ERROR_INTERRUPT 201 ERROR_RELOCSRC_ 
CHAIN_EXCEEDS_ 
SEGLIMIT 

108 ERROR_DRIVE_LOCKED 206 ERROR_FILENAME _ 
EXCED_RANGE 

123 ERROR_INVALID_NAME 295 ERROR_INIT_ROUTINE_ 


FAILED 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSMODULEMGR 
Ordinal: 318 DLL: DOSCALLS 
SEE ALSO 


DosFreeModule -11, DosQueryModuleName -17, 
DosQueryProcAddr -18, _ loadmod 


NOTES 


For DLLs that link to other DLLs, it is possible that an ERROR_FILE_ 
NOT_FOUND or ERROR PATH NOT FOUND indicates that one of 
the DLLs to which the requested DLL is linked cannot be found. 

If the DLL to be loaded has already been loaded by another 
process, the DLL will not be loaded into memory twice, but access for 
the calling process will be provided. 

An ERROR INVALID MODULETYPE error will be returned if 
the operating system thinks you are trying to load something other 
than a DLL (such as an executable). Use EXEHDR.EXE (from the 
toolkit) to determine which type the system thinks your module’s 


type is. 
RESTRICTIONS/WARNINGS 


@ This call cannot be made from ring 2 if the DLL has an initialization 
routine; the process will be terminated. 

@ If the module has an initialization routine that is in a code segment 
that has I/O privilege, the process issuing DosLoadModule will 
cause a general protection fault and terminate. 





@ DosQueryApp Type Module Management 


Returns the application type of an executable file. 
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SYNTAX 
APIRET DosQueryAppType(PSZ pszExeFile, PULONG pulAppType) 


PARAMETERS 

pszExeFile - input 

A null-terminated string containing the name of the application to 
query. If no path is specified, the current path, and then the directo- 
ries specified in the PATH environment string will be searched until 
the executable is found. If no extension is specified, .exe extension is 
assumed. 

pulAppType - output 

The address of a ULONG to receive the flags describing the applica- 
tion type. The type is determined by reading the executable’s file 
header. The following flags are valid: 


Constant Description 


FAPPTYP_NOTSPEC 0x0000 No application type was 
specified in the .exe header. 


FAPPTYP_NOTWINDOWCOMPAT 0x0001 The executable runs full 


screen only. 


FAPPTYP_WINDOWCOMPAT Ox0002 The executable can be run in 
a VIO window or full screen. 


FAPPTYP_WINDOWAPI 0x0003 The executable type is 
Presentation Manager. 


FAPPTYP BOUND 0x0008 The executable uses the 
Family APIs and runs in 
either DOS or OS/2 sessions. 
The FAPPTYP_NOTSPEC 
through FAPPTYP_ 
WINDOWAPI flags still apply. 


FAPPTYP_ DLL Ox0010 ‘The executable is a DLL. 

FAPPTYP_PHYSDRV 0x0040 The executable is a device 
driver. 

FAPPTYP_VIRTDRV Ox0080 The executable is a virtual 


device driver. 


FAPPTYP_PROTDLL Ox0100 The executable is a protected 
memory DLL. 
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FAPPTYP_WINDOWSREAL 0x0200 The executable is type 
Windows real mode. 

FAPPTYP_WINDOWSPROT 0x0400 The executable is type 
Windows protect mode. 

FAPPTYP_WINDOWSPROT31 0x1000 The executable is type 
Windows 3.1 protect mode. 

FAPPTYP_ 32BIT 0x4000 The executable is 32-bit. 

RETURNS 

0 NO_ERROR 32 ERROR_SHARING_ 
VIOLATION 


2 ERROR_FILE_NOT_FOUND 108 ERROR_DRIVE_LOCKED 
3 ERROR_PATH_NOT_FOUND — 110 ERROR_OPEN_FAILED 


4 ERROR TOO_MANY_ 191 ERROR INVALID _ 
OPEN_FILES EXE_ SIGNATURE 
11 ERROR BAD FORMAT 192 ERROR _ EXE MARKED _ 
INVALID 
15 ERROR INVALID DRIVE 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSMODULEMGR 
(APIs) INCL_DOS- 
FILEMGR (Constants) 
Ordinal: 325 DLL: DOSCALLS 
SEE ALSO 


DosQueryProcType -20 


NOTES 


The application type is determined by the options used in the module 
definitions file (.DEF). 

The Presentation Manager shell uses this function to determine 
the application type. 

This function is useful to determine if executables, DLLs, and de- 
vice drivers exist and if they are in running condition. Executables that 
have linker errors or corruption are not in runnable condition. 
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@ DosQueryModuleHandle Dynamic Linking 


Returns the module handle of a previously loaded DLL. 


SYNTAX 

APIRET DosQueryModuleHandle(PSZ pszModuleName, PHMODULE 
pModuleHandle) 

PARAMETERS 


pszModuleName - input 

A null-terminated string containing the name of the previously loaded 
DLL. 

pModuleHandle - output 

The address of an HMODULE to receive the module handle. 


RETURNS 

0 NO_ERROR 123 ERROR INVALID NAME 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSMODULEMGR 
Ordinal: 319 DLL: DOSCALLS 

SEE ALSO 


DosFreeModule -11, DosLoadModule -12, DosQueryAppType -14, 
DosQueryModuleName -17 


RESTRICTION/WARNINGS 


@ The module name must match the name of a previously loaded 
DLL, otherwise ERROR_INVALID_ NAME is returned. This method 
can be used to determine if a DLL has been loaded. 





@® DosQueryModuleName Dynamic Link 


Returns the fully qualified path of a DLL from a referenced module 
handle. 
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SYNTAX 


APIRET DosQueryModuleName (HMODULE hmodModuleHandle, 
ULONG uwlBufferLength, PCHAR 
pModuleNameBuffer) 


PARAMETERS 


hmodModuleHandle - input 

The module handle whose fully qualified path is to be queried. 
ulBufferLength - input 

The size of pModuleNameBuffer, in bytes. 

pModuleNameBuffer - output 

The address of a buffer to receive the fully qualified module name. 


RETURNS 


0 NO_ERROR 24 ERROR_BAD_ LENGTH 
6 ERROR_INVALID_ HANDLE 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSMODULEMGR 
Ordinal: 320 DLL: 


SEE ALSO: 
DosLoadModule -12, DosQueryModuleHandle -17 


RESTRICTIONS/WARNING 
@ If the buffer is too small, ERROR BAD LENGTH is returned. 





DosQueryProcAddr Dynamic Linking 


Given the module handle, returns the address of the specified proce- 
dure. 


SYNTAX 


APIRET DosQueryProcAddr(HMODULE hmodModuleHandle, LONG 
ulOrdinal, PSZ pszProcedureName, PFN 
* bpProcedureAddress) 


PARAMETERS 
hmodModuleHandle - input 
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The module handle of the DLL that contains the procedure address to 
be loaded. 

ulOrdinal - input 

The ordinal of the procedure whose address is to be loaded. If this 
value is not zero, then pszProcedureName is ignored. 

pszProcedureName - input 

A null-terminated string containing the name of the procedure whose 
address is desired. This value is checked only if wlOrdinalis zero. 
ppProcedureAddress - output 

The address of a PFN that is to be set to the desired procedure address. 


RETURNS 
0 NO_ERROR 127 ERROR PROC _NOT_ 
FOUND 
6 ERROR INVALID HANDLE 65079 ERROR ENTRY IS_ 
CALLGATE 
123 ERROR_INVALID_NAME 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSMODULEMGR 
Ordinal: B21 DLL: DOSCALLS 
SEE ALSO 


DosFreeModule -11, DosLoadModule -12, DosQueryModuleName -17, 
DosQueryProcType -20 


NOTES 


It is quicker and more reliable to query procedure addresses by ordi- 
nal when possible, assuming that the DLL’s ordinals have been explic- 
ity assigned. Procedure names can change in a DLL, and specifying an 
ordinal that matches an assigned ordinal in the DLL’s DEF file ensures 
that name changes will not break your code. 


RESTRICTIONS/WARNINGS 


@ The module handle used must reference a DLL that is currently 
loaded, otherwise ERROR INVALID HANDLE will be returned. 

@ If the procedure address to be queried is in the DOSCALLS.DLL 
module or any other module that contains only ordinals, you must 
query it via ordinal, otherwise ERROR_INVALID_NAME will be re- 
turned. 
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@ If the address to be queried has an entry point that can only be ac- 
cessed via a call gate, then ERROR_ENTRY_IS_CALLGATE is re- 
turned. : 

If the procedure could not be found in the DLL, then ERROR_ 

PROG_NOT_FOUND is returned. Here are a few of the possible 

reasons for this error: 

— The procedure has not been exported by the module definitions 
file (.DEF). Make sure there is an export defined for the proce- 
dure in the DFF file. 

— There is an error in the case of the procedure. Unless the DLL 
was linked with the NOIGNORECASE (/NOI) option, the pro- 
cedure name (pszProcedureName) must be specified in all up- 
percase. 

— The name of the procedure was misspelled. 

Function addresses returned by DosQueryProcAddr have _System 

linkage. Functions compiled with CSet++ use Optilink linkage by de- 

fault. Make sure the linkages match, otherwise unpredictable results 
will occur. 





DosQueryProc Type Dynamic Linking 


Indicates whether the specified procedure is 16-bit or 32-bit. 


SYNTAX - 


APIRET DosQueryProcType(HMODULE hmodModuleHandle, ULONG 
ulOrdinal, PSZ pszProcedureName, 
PULONG pulProcType) 


PARAMETERS 


hmodModuleHandle - input 

The module handle of the DLL that contains the procedure whose 
type is to be queried. 

ulOrdinal - input 

The ordinal value of the procedure whose type is to be queried. If this 
value is not zero, then pszProcedureName is ignored. 

pszProcedureName - input 

A null-terminated string that contains the procedure to be queried. 
This value is ignored if an ordinal is provided in the ulOrdinal para- 
meter. 
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pulProcType - output 
The address of a ULONG to receive the type flag. The following types 
are supported: 


Constant Description 

PT_l16BIT Q The procedure is 16-bit. 

PT_32BIT 1 The procedure is 32-bit. 

RETURNS 

0 NO_ERROR 123 ERROR_INVALID _ 
NAME 

6 ERROR INVALID HANDLE 182 ERROR INVALID _ 
ORDINAL 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSMODULEMGR 

Ordinal: 586 DLL: DOSCALLS 

SEE ALSO 


DosFreeModule -22, DosLoadModule -12, DosQueryProcAddr -18 


RESTRICTIONS/WARNINGS 


@ The DLL containing the procedure must be loaded, otherwise ER- 
ROR INVALID HANDLE will be returned. 


Dynamic Resource Management Functions 





DosFreeResource frees a resource object loaded with DosGetResource 


(pg. 22). 


DosGetResource returns the address of the specified resource object 


(pg. 22). 


DosQueryResourceSize returns the size of the specified resource ob- 
ject (pg. 24). 
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@® DosFreeResource Resource Management 





Frees a resource loaded with DosGetResource. 


SYNTAX 
APIRET DosFreeResource(PVOID pResourceAddress) 


PROCEDURE 


pResourceAddress - input 
A pointer to the resource to be freed. 


RETURNS 

0 NO_ERROR 5 ERROR ACCESS DENIED 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSRESOURCES 
Ordinal: 353 DLL: DOSCALLS 

SEE ALSO 


DosGetResource -22, DosQueryResourceSize -24 


NOTES 


Once the last reference to a resource is freed, the memory is made 
available for reuse by the system. However, for performance reasons, 
the resource will remain in memory until the system determines that it 
can no longer satisfy memory requests. ‘This way, the system will not 
have to reload the resource from disk if it is requested again. 





DosGetResource Resource Management 





Loads the specified resource into memory and returns a pointer to it. 


SYNTAX 


APIRET DosGetResource(HMODULE hmodModuleHandle, VLONG 
ull ype, ULONG ulResourcelD, PPVOID 


ppOffset) 


PARAMETERS 
hmodModuleHandle - input 
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The module handle of the DLL that contains the resource to be 
loaded. If this value is zero, then the resource will be loaded from the 


calling executable. 


ulType - input 


Specify one of the following resource types: 


Constant 
RT_POINTER 
RT_BITMAP 
RT_MENU 
RT_DIALOG 
RT_STRING 
RT_FONTDIR 
RT_FONT 
RT_ACCELTABLE 
RT_RCDATA 
RT_MESSAGE 
RT_DLGINCLUDE 
RT_VKEYTABLE 
RT_KEYTBL 
RT_CHARTBL 
RT_DISPLAYINFO 
RT_FKASHORT 
RT_FKALONG 
RT_HELPTABLE 


RT_HELPSUBTABLE 


RT_FDDIR 
RT_FD 


ulResourcelD - input 
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Description 
Mouse pointer 
Bitmap 
Menu template 
Dialog template 
String table 
Font directory 
Font 
Accelerator table 
User-defined binary data 
Error messages 
Dialog include file name 
Key to virtual key tables 
Key to UGL tables 
Glyph to character tables 
Screen display information 
Function key area—short form 
Function key area—long form 
Help table 
Help subtable 
DBCS unique font driver directory 


DBCS unique font driver 


The identifier of the 32-bit resource. 


ppOffset - output 


The address of a PVOID that is to receive the offset of the resource. 


24 


OS/2® Warp Control Program API 


RETURNS 


0 NO_ERROR 87 ERROR INVALID PARAMETER 
6 ERROR INVALID HANDLE * 


OTHER INFO 


Include file: bsedos.h Define: INCL. DOSRESOURCES 
Ordinal: 352 DLL: DOSCALLS 


SEE ALSO 


DosFreeModule -11, DosFreeResource -22, DosLoadModule -12, 
DosQueryResourceSize -24 


NOTES 


The resources returned are read-only objects that can be dynamically 
accessed. 

The resource objects this routine loads are those compiled via the 
resource compiler (RC.EXE) and then appended to an executable 
or DLL. 





DosQueryResourceSize Resource Management 


Returns the size of the specified resource. 


SYNTAX 


APIRET DosQueryResourceSize (HMODULE hmodModuleHandle, 
ULONG ulType, ULONG 
ulResourcelD, PULONG pulSize) 


PARAMETERS 


hmodModuleHandle - input 

The module handle of the DLL that contains the resource to be queried. 
If zero, the calling executable will be queried for the resource. 

ulType - input 

Specify one of the following resource types: 


Constant Description 
RT_POINTER 1 Mouse pointer 
RT_BITMAP 2 Bitmap 
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RT_ MENU 3 Menu template 

RT_DIALOG 4 Dialog template 

RT_STRING 5 String table 

RT_FONTDIR 6 Font directory 

RT_FONT 7 Font 

RT_ACCELTABLE 8 Accelerator table 
RT_RCDATA 9 User-defined binary data 
RT_MESSAGE 10 Error messages 
RT_DLGINCLUDE 11 Dialog include file name 
RT_VKEYTABLE 12 Key to virtual key tables 
RT_KEYTBL 13. Key to UGL tables 
RT_CHARTBL 14 Glyph to character tables 
RT_DISPLAYINFO 15 Screen display information 
RT_FKASHORT 16 ~=Function key area—short form 
RT_FKALONG 17 ‘Function key area—long form 
RT_HELPTABLE 18 Help table 
RT_HELPSUBTABLE 19 Help subtable 

RT_FDDIR 20 DBCS unique font driver directory 
RT_FD 21 DBCS unique font driver 


ulResourcelD - input 

The ID of the resource to be queried. 

pulSize - output 

The address of a ULONG to receive the size, in bytes, of the resource. 


RETURNS 

0 NO_ERROR 87 ERROR INVALID PARAMETER 
6 ERROR INVALID HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL._DOSRESOURCES 


Ordinal: 572 DLL: DOSCALLS 
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SEE ALSO 
DosFreeResource -22, DosGetResource -22, DosLoadModule -12 


NOTES 


This function queries resources built using the resource compiler 
(RC.EXE). 

This function can determine the size of resources loaded from 16- 
bit executables and DLLs even though the size may not be explicitly 
stored in the resource. 





Error Processin 





.. Program functions return nonzero return codes when an 
error has occurred. Sometimes, these return codes need further 
classification before an application can determine the appropriate 
processing to perform. DosErrClass may be used to obtain this infor- 
mation. It takes the error code as a parameter and returns the error 
classification, the suggested action for the application to take, and the 
location of the error. 

When OS/2 encounters a hard error such as system exception, or 
accessing a disk drive with no diskette, the system, by default, will display 
a hard error or exception popup screen. Often, an application would be 
better served by performing its own error handling for these situations. 
DosError can be used to enable or disable hard error popups and ex- 
ception popups. However, when an exception occurs, the application 
will be terminated regardless of whether exception popups are disabled. 


Error Functions 





DosErrClass returns additional information on a previously returned 
error code (pg. 28). 
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DosError enables or disables hard error and exception popup screens 


(pg. 30). 





@ DosErrClass Errors 





Returns additional information about a previously returned error 
from a Control Program function. 


SYNTAX 


APIRET DosErrClass(ULONG ulError, PULONG pulClassification, 
PULONG pulAciion, PULONG pulLocus) 


PARAMETERS 


ulError - input 

The nonzero return code of a previously called Control Program func- 
tion. 

pulClassification - output 

The classification of the error, as follows: 


Classification Description 

ERRCLASS OUTRES 1 Out of resources. 

ERRCLASS_TEMPSIT 2 Temporary situation. 

ERRCLASS_ AUTH 3 Authorization failure. 

ERRCLASS_INTRN 4 Internal error. 

ERRCLASS HRDFAIL 5 Hardware device failed. 

ERRCLASS_SYSFAIL 6 System failure. 

ERRCLASS_APPERR 7 Probable application failure. 

ERRCLASS NOTFND 8 Item not found. 

ERRCLASS_BADFMT 9 Bad format or data for the function type. 

ERRCLASS_LOCKED 10 Resource or data is locked. 

ERRCLASS_MEDIA 11 Incorrect media, or cyclic redundancy 
check. 

ERRCLASS_ALREADY 12 Action already performed, or resource 


already exists. 
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ERRCLASS_ UNK 13. Unclassified. 
ERRCLASS_CANT 14 Cannot perform requested action. 
ERRCLASS_TIME 15 Time-out. 


pulAction - output 
The suggested action for the application to perform: 


Suggested Action Description 

ERRACT_RETRY 1 Retry the action immediately. 
ERRACT_DLYRET 2 Retry the action later. 

ERRACT_USER 3 Bad user input; get correct values and retry. 
ERRACT_ ABORT 4 (Clean up and terminate. 

ERRACT_ PANIC 5 ‘Terminate immediately. 

ERRACT_IGNORE 6 Ignore the error. 

ERRACT_INTRET 7 Retry the action after user intervention. 


pulLocus - output 
The location where the error originated: 


Error Location Description 
ERRLOC_UNK 1 Location unknown 
ERRLOC_DISK 2 Random access device 
ERRLOC_NET 3 Network 
ERRLOC_SERDEV 4 Serial device 
ERRLOC_MEM 5 In memory 


RETURNS 

0 NO_ERROR 87 ERROR INVALID PARAMETER 

OTHER INFO 

Include file: bsedos.h, bseerr.h Define: INCL _DOSMISC, 
INCL_DOSERRORS 

Ordinal: 211 DLL: DOSCALLS 

SEE ALSO 


DosError -30 
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NOTES 


Even if no control program function was called prior to this one, no er- 
ror will be returned. 





DosError Errors 


Enables or disables exception and hard error popups. 


SYNTAX 
APIRET DosError(ULONG uwlFlags) 


PARAMETERS 

ulFlags - input 

The following flags may be logically Ored together (default values are 
italicized): 


Flags Description 

FERR_DISABLEHARDERR 0x00 Disable hard error popups. 

FERR_ENABLEHARDERR 0x01 Enable hard error popups. 

FERR_ENABLEEXCEPTION 0x00 Disable exception popups. 

FERR_DISABLEEXCEPTION 0x02 Enable exception popups. 

RETURNS 

0 NO_ERROR 87 ERROR_INVALID_PARAMETER 

OTHER INFO 

Include file: bsedos.h, bseerr.h Define: INCL _DOSMISC, 
INCL_DOSERRORS 

Ordinal: 212 DLL: DOSCALLS 

SEE ALSO 


DosErrClass -28 


NOTES 


If DosError is not called, the system default for hard errors and excep- 
tions is to display an error popup. 





Fxceptions 





ho are error conditions that occur that require the flow of 
execution to be transferred to a special procedure (commonly re- 
ferred to as an exception handler). Exceptions are typically caused 
when the processor executes instructions that result in conditions like 
protection violations, divide-by-zero errors, I/O errors, and stack 
faults. OS/2, 32-bit, also converts signals into exceptions that are re- 
ferred to as signal exceptions. Signals exceptions are caused by user ac- 
tivity such as pressing Ctrl-C or Ctrl-Break, and via code such as calling 
DosKillProcess. Except for Guard Page exceptions, the default pro- 
cessing for exceptions is to terminate the application. However, appli- 
cations can register their own exception handlers with the system that 
will receive control whenever an exception occurs. 


Exception Handlers 


Exception handlers are thread-specific, and are registered with the sys- 
tem by calling DosSetExceptionHandler. The new exception handler 
is added to the beginning of a chain of exception handlers, so that the 
last handler registered will be the first called when an exception occurs. 
This allows exception handlers to be nested, so that if the exception 
handler chooses not to handle the exception it will be passed onto the 
next handler in the chain. When an exception handler is no longer 
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needed it can be removed by calling DosUnsetExceptionHandler. 
Exception handlers can also be removed by calling DosUnwind- 
Exception, which performs similarly to DosUnsetExceptionHandler, 
but calls the exception handler first. 

The ability to nest handlers and register and remove them at will 
provides the flexibility needed to do handling on a function-by-func- 
tion level, or even line by line. See “Exception Handler Information” 
on pg. 51 for more information on exception handlers. 


Synchronous and Asynchronous Exceptions 


Most exceptions that are generated are synchronous, which are excep- 
tions that occur due to the execution of an instruction by the currently 
running thread. Asynchronous exceptions are caused by events asyn- 
chronous (that is, external) to the thread that receives the exception. 
An example of an asynchronous exception is the user pressing Ctrl-C 
or Ctrl-Break. 


Must-complete Sections 


Sections of code can be protected from being interrupted by asyn- 
chronous exceptions. These are called must-complete sections. Must- 
complete sections are begun by calling DosEnterMustComplete, and 
ended by calling DosExitMustComplete. Must-complete sections can 
be nested, and are tracked by a counter. When the counter is zero, the 
code is no longer protected from asynchronous exceptions. If an asyn- 
chronous exception occurs while code is executing in a must complete 
section, it is deferred by the system until the must-complete counter 
reaches zero. 

An application can determine the current level of must-complete 
nesting by calling DosGetInfoBlocks and examining the ustib2_ usMC- 
Count flag of the TIB2 structure. 

Synchronous exceptions and user-defined exceptions cannot be 
deferred, and are not affected by must-complete sections. However, 
the processing for this category of exceptions can be deferred by fol- 
lowing these steps: 


1. Register a “special” exception handler that will be used just to trap 
synchronous exceptions. 
2. Just before entering the must-complete section, set a flag to FALSE. 
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3. If a synchronous exception is raised while in a must-complete sec- 
tion, have the “special” handler set the flag to TRUE. 

4. Immediately after exiting the must-complete section check the flag 
to see if it is set. If so, then an exception occurred while in the must- 
complete section. 

5. Remove the special exception handler. 


Of course, this does not really stop the exception from occurring while 
in the must-complete section, but merely delays the processing of it un- 
til after the must-complete section has ended. 


Signal Exceptions 


Registering an exception handler only causes exceptions to be passed to 
an exception handler. A process must call DosSetSignalException- 
Focus after calling DosSetExceptionHandler to receive signal excep- 
tions. Signal exceptions are always generated on thread 1 of the 
process receiving the exception. Calling DosSetSignalFocus with the 
flag set to TRUE will cause a counter to be incremented by 1. Calling 
DosSetSignalFocus with the flag set to FALSE causes the counter to be 
decremented by 1. When a signal exception occurs, the system checks 
the counter of the last process to set the signal focus within the same 
session, and if it is not zero, it sends the signal exception to the regis- 
tered exception handler on thread | of that process. Note that signal 
focus is owned at the session (or screen group) level. So, the last 
process in the same session to call DosSetSignalFocus with the flag set 
to TRUE will be the one to receive any signal exceptions. It does not 
matter which process has the highest focus count. 

If there is more than one exception handler registered for the 
process receiving the signal exceptions, the 32-bit ones will be called 
first, followed by any 16-bit exception handlers. In order for a process 
to continue receiving signal exceptions, its handler must either ac- 
knowledge the exception by calling DosAcknowledgeSignalException 
or return XCPT_ CONTINUE_EXECUTION. The typematic capability 
of keyboards allows Ctrl-C and Ctrl-Break to be repeated many times by 
holding down the keys. For this reason, the system will hold the signal 
exceptions until the exception handler returns XCPT_CONTINUE_ 
EXECUTION or calls DosAcknowledgeSignalException. The excess 
signal exceptions are not queued by the system. 

The Ctrl-C and Ctrl-Break signal exceptions can be sent to other 
processes by calling DosSendSignalException. No other type of signal 
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exception or regular exception (including user-defined exceptions) 
can be sent to another process. 


Raising Exceptions 


A process may simulate the occurrence of a synchronous or asynchro- 
nous exception by calling DosRaiseException. For example, an appli- 
cation that is emulating a floating point processor can use DosRaise- 
Exception to simulate a floating point overflow exception. 

Raising an exception causes the machine state of the current 
thread to be saved into a CONTEXTRECORD structure. The Excep- 
tionAddress of the EXCEPTIONREPORTRECORD structure will be 
set to the return address of the caller. Then each exception handler 
in the chain is called with the saved context record structure and 
exception report record structures. If the exception is a continuable 
exception and an exception handler returns XCPT_CONTINUE_EX- 
ECUTION, then the saved context information is restored into the 
machine before the handler returns. If the instruction pointer in the 
context record structure has been modified, control will not return 
back to the caller, but to the new instruction pointed to by the instruc- 
tion pointer. 

If desired, the caller can set the EH_ NONCONTINUABLE bit in 
the exception report record structure, which will ensure that execution 
will not be returned to the caller. Once this bit is set, the process is al- 
ways terminated. If the handler changes this flag and then returns 
XCPT_CONTINUE_EXECUTION, the system will generate an XCPT_- 
NONCONTINUABLE_EXCEPTION exception and then terminate the 
application. 


User-defined Exceptions 


User-defined exceptions are raised by an application simply by calling 
DosRaiseException and passing the value of the user-defined excep- 
tion to the call. See the “System Defined Exceptions” section on pg. 52 
for the format of exception values. 

Any exception handlers that do not recognize the exception will 
just return XCPT_CONTINUE_SEARCH. Once the application’s ex- 
ception handler is finished processing the exception, it should return 
XCPT_CONTINUE_EXECUTION so that the exception will stop be- 
ing passed down the chain of exception handlers. If the user-defined 
exception is not handled, the system will terminate the application. 
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Unwinding Exceptions 


Exception handlers are often used to clean up the resources of a ter- 
minating thread and to clean up the resources used during nonlocal 
goto operations (see the C library function setymp). Unwinding ex- 
ceptions is the process of calling an exception handler before it is re- 
moved. DosUnwindException may be used to walk backward through 
the exception handler chain and call and unwind all exception han- 
dlers up to but not including the specified exception handler. 
DosUnwindException can also unwind all the exception handlers of 
the thread, or unwind all the exception handlers of the thread and 
then terminate the thread. When an unwind operation is underway, 
the EH_UNWINDING flag will be set in the exception flags field of the 
EXCEPTIONREPORTRECORD data structure. Additionally, if the un- 
wind operation includes the termination of the thread, then the 
EH_EXIT_UNWIND flag will be set. 

DosUnwindException never returns unless the stack is corrupted. 
DosUnwindException takes an instruction pointer address as a para- 
meter that indicates where execution should begin after the last ex- 
ception handler returns. Some high-level languages cannot use 
DosUnwindException because they are not capable of passing an in- 
struction pointer address (one of the required parameters). 


Nested Exceptions 


It is possible that an exception will occur while an exception is being 
processed. To avoid infinite recursion within exception handlers, the 
handler should first check for the EH_NESTED_CALL flag in the EX- 
CEPTIONREPORTRECORD structure and, if set, return XCPT_CON- 
TINUE_SEARCH immediately without handling the exception. 


Exiting 


When a process termination exception occurs, it will be raised and 
processed for each thread. When all of the threads but the main 
thread have terminated, any exit list routines that are registered will be 
executed. Finally, if there is a DLL linked to the application with a DLL 
initialization/termination routine, it will be invoked. If the application 
is handling a process termination exception, it should eventually pass 
on the exception so that the normal exit list processing can occur. 
Threads should not use DosCreateThread, DosExecPgm, DosStart- 
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Session, or DosExit after they have received a process termination ex- 
ception. 


Restrictions and Warnings 


@ Presentation Manager applications that wish to receive process sig- 
nal exceptions must not create any Presentation Manager message 
queues on the main thread. All signal exceptions are generated on 
the main thread (thread 1). 

® DosSendSignalException may be used to send only a Ctrl-C or Crtl- 
Break to child process. 

@ There is no interface for sending user-defined signals or raising any 
type of exception on another process. 

@ Exception handler registration records must be created on the 

stack. Exception handlers must also be removed before the function 

in which they are registered returns. 

Exception handlers should be carefully coded to handle only the ex- 

ceptions of interest, otherwise, undesired side effects may occur. 

Exception handlers should always check for the nested exception 

flag and, if set, return XCPT_CONTINUE_SEARCH, otherwise infi- 

nite recursion may occur. 


Exception Handling Functions 





DosRaiseException raises a synchronous or asynchronous exception 
(pg. 36). 

DosSetExceptionHandler registers an exception handler for the call- 
ing thread (pg. 38). 

DosUnsetExceptionHandler deregisters an exception handler for the 
calling thread (pg. 39). 

DosUnwindException unwinds all exceptions up to, but not including, 
the specified exception for the calling thread (pg. 40). 





DosRaiseException Exceptions 


Raises a synchronous or asynchronous exception on the calling thread. 


Exceptions af 


SYNTAX 

APIRET DosRaiseException (PEXCEPTIONREPORTRECORD 
piExRepRec) 

PARAMETERS 


pExRepRec - input 

A pointer to an EXCEPTIONREPORTRECORD containing the infor- 
mation necessary to raise the exception. The system will automatically 
fill in the nested EXCEPTIONREPORTRECORD pointer, the applica- 
ble handler flags, and the exception address. 


RETURNS 

0 NO_ERROR 

OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 356 DLL: DOSCALLS 

SEE ALSO 


DosAcknowledgeSignalException -42, DosEnterMustComplete -46, 
DosExitMustComplete -47, DosSendSignalException -43, 
DosSetExceptionHandler -38, DosUnsetException Handler -39, 
DosUnwindException -40 


NOTES 


This function can be used to raise a synchronous exception that oc- 
curred while in a must-complete section, or to simulate synchronous 
and asynchronous exceptions that are system- or user-defined. 

See the “Must-Complete” section of the chapter introduction for 
more information on deferring synchronous exceptions for must-com- 
plete sections. 

Raising an exception causes the machine state of the current thread 
to be saved into a CONTEXTRECORD structure. The Exception- 
Address of the EXCEPTIONREPORTRECORD structure will be set to 
the return address of the caller. Then each exception handler in the 
chain is called with the saved context record structure and exception 
report record structures. If the exception is a continuable exception 
and an exception handler returns XCPT_CONTINUE_EXECUTION, 
the saved context information is restored into the machine before the 
handler returns. If the instruction pointer in the context record struc- 
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ture has been modified, control will not return back to the caller, but 
to the new instruction pointed to by the instruction pointer. 

If desired, the caller can set the EH _NONCONTINUABLE bit in 
the exception report record structure, which will ensure that execu- 
tion will not be returned to the caller. Once this bit is set, an exception 
handler cannot change it and the system will enforce it. When this flag 
is set, the process is always terminated. If the handler changes this flag 
and then returns XCPT_CONTINUE_EXECUTION, the system will 
generate an XCPT_NONCONTINUABLE_EXCEPTION exception 
and then terminate the application. 





DosSetExceptionHandler Exceptions 


Registers an exception handler for the calling thread. 


SYNTAX 

APIRET DosSetException Handler (PEXCEPTIONREGISTRATION- 
RECORD pExRegRec) 

PARAMETERS 


pExRegRec - input 

The address of an EXCEPTIONREGISTRATIONRECORD that con- 
tains the information about the exception handler to be registered. 
The exception registration record must be on the stack. 


RETURNS 

0 NO_ERROR 

OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 354 DLL: DOSCALLS 

SEE ALSO 


DosAcknowledgeSignalException -42, DosEnterMustComplete -46, 
DosExitMustComplete -47, DosRaiseException -36, 
DosSendSignalException -43, DosSetSignalExceptionFocus -44, 
DosUnsetExceptionHandler -39, DosUnwindException -40 


Exceptions 39 


NOTES 


Exception handlers are thread-specific. Each new exception handler is 
added to the beginning of a chain so that the last handler registered 
will be the first to be called when an exception occurs. This allows ex- 
ception handlers to be nested so that if the exception handler chooses 
not to handle the exception, it will be passed onto the next handler in 
the list. When an exception handler is no longer needed, it can be re- 
moved by calling DosUnsetExceptionHandler. 


RESTRICTIONS/WARNINGS 


@ The EXCEPTIONREGISTRATIONRECORD must have been cre- 
ated on the stack—not in the data segment. This allows the operat- 
ing system to determine the ordering of the records by their ad- 
dresses on the stack and protects the chain from corruption in 
multithreaded programs. Therefore, global variables and statics 
cannot be used to hold this record. If a global or static variable is 
used, no error will be returned. 

Exception handlers must be removed before the function they were 
registered in returns (see DosUnsetExceptionHandler). 

If more than one exception handler will be registered within the 
same procedure, each record must have a higher position (that is, a 
lower address) on the stack than the previously registered handler. 





DosUnsetExceptionHandler Exceptions 


Removes a previously registered exception handler for the calling 
thread. 


SYNTAX 

APIRET DosUnsetExceptionHandler(PEXCEPTIONREGISTRA- 
TIONRECORD pExRegRec) 

PARAMETERS 


pExRegRec - input 
The address of an EXCEPTIONREGISTRATIONRECORD that con- 
tains the information about the exception handler to be removed. 


RETURNS 
0 NO_ERROR 87 ERROR_INVALID_PARAMETER 
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OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 355 DLL: DOSCALLS 

SEE ALSO 


DosAcknowledgeSignalException -42, DosEnterMustComplete -46, 
DosExitMustComplete -47, DosRaiseException -36, 
DosSendSignalException -43 DosSetSignalExceptionFocus -44, 
DosUnwindException -40 


NOTES 


If the call is issued when there are no registered exception handlers for 
the calling thread, ERROR_INVALID_PARAMETER is returned. 





@® DosUnwindException Exceptions 


Unwinds all exception handlers up to, but not including, the specified 
handler for the calling thread. 


SYNTAX 


APIRET DosUnwindException (PEXCEPTIONREGISTRATION- 
RECORD pExRegRec, PVOID pTargetlF 
PEXCEPTIONREPORTRECORD 


pExRepRec) 


PARAMETERS 
pkExRegRec - input 
Specify either the address of the exception where the unwind should 


stop, or: 

Constant Description 

END_OF CHAIN -1 Unwind all registered exception handlers 
for the calling thread. 

UNWIND_ALL 0 Unwind all registered exception handlers 


for the thread, and then end the thread. 
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plargetlP - input 

The address of the instruction to begin executing after the unwind op- 
eration is completed. 

pkExRepRec - input 

The address of an EXCEPTIONREPORTRECORD that contains the 
information to pass to the unwound exception handlers. Specify 
NULL to have the system build a default report record that specifies an 
XCPT_UNWIND exception. 


RETURNS 

OQ NO_ERROR 1 ERROR_INVALID_FUNCTION 

OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 357 DLL: DOSCALLS 

SEE ALSO 


DosAcknowledgeSignalException -42, DosEnterMustComplete -46, 
DosExitMustComplete -47, DosRaiseException -36, 
DosSendSignalException -43, DosSetException Handler -38, 
DosSetSignalExceptionFocus -44, DosUnsetExceptionHandler -39 


NOTES 


If the value for pExRegRecis NULL, then each exception handler called 
will receive the XCPT_UNWIND exception and have the EH_UN- 
WINDING or EH_EXIT_UNWINDING bit set. When the exception 
handler returns, the EXCEPTIONREGISTRATIONRECORD is re- 
moved from the list, and the next exception handler is unwound. 

DosUnwindException never returns unless the stack is corrupted. 

If an invalid EXCEPTIONREGISTRATIONRECORD is specified, 
an XCPT_INVALID_UNWIND_TARGET exception is raised and the 
chain is not unwound. 

If a handler that is being unwound hits an exception that has 
called DosUnwindException, the first unwind operation is aban- 
doned, and the second unwind begins processing. If an unwinding 
handler calls DosUnwindException, an XCPT_INVALID_TARGET ex- 
ception is raised. 
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Signal Exception Functions 





DosAcknowledgeSignalException indicates that the calling process 
wishes to continue receiving signal exceptions (pg. 42). 
DosSendSignalException sends a Ctrl-C or Ctrl-Break signal exception 
to the target descendant process (pg. 43). 
DosSetSignalExceptionFocus sets or unsets the calling process as the 
target process for signal exceptions for the session (pg. 44). 





@ DosAcknowledgeSignalException Exceptions 


Indicates that the process wishes to continue receiving signal excep- 
tions. 


SYNTAX 
APIRET DosAcknowledgeSignalException (ULONG wilSignalNumber) 


PARAMETERS 


ulSignalNumber - input 
The system-defined signal number being acknowledged. 


RETURNS 

Q NO_ERROR 209 ERROR_INVALID_SIGNAL_ NUMBER 

OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 418 DLL: DOSCALLS 

SEE ALSO 


DosSendSignalException -43, DosSetSignalExceptionFocus -44 
NOTES 


This call is used to indicate that the calling process wishes to continue 
receiving system-defined signal exceptions. This call is not necessary if 
the handler is returning XCPT_CONTINUE_EXECUTION. 


Exceptions 43 





@ DosSendSignalException Signal Exceptions 


Sends either a Ctrl-C or Ctrl-break signal exception to the target de- 
scendant process. 


SYNTAX 

APIRET DosSendSignalException (PID pidTarget, ULONG wulSignal- 
Exception) 

PARAMETERS 


pidTarget - input 

The descendant process ID to send the signal exception to. 
ulSignalException - input 

The signal exception number to send. Only the following signals can 


be sent: 
Signal Exception Description 
XCPT_ SIGNAL INTR 1 Ctrl-C signal. 
XCPT_SIGNAL_ BREAK 4 Ctrl-Break signal. 
RETURNS 

0 NO_ERROR 205 ERROR_NO_SIGNAL_ 


SENT 
1 ERROR_INVALID_FUNCTION 209 ERROR_INVALID_ 
SIGNAL_NUMBER 
156 ERROR_SIGNAL_ REFUSED 303 ERROR_INVALID _ 


PROCID 
OTHER INFO 
Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 
Ordinal: 379 DLL: DOSCALLS 
SEE ALSO 


DosAcknowledgeSignalException -42, DosEnterMustComplete -46, 
DosExitMustComplete -47, DosRaiseException -36, 
DosSetExceptionHandler -38, DosSetSignalExceptionFocus -44, 
DosUnsetExceptionHandler -39, DosUnwindException -40 
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NOTES 


This call will only send signal exceptions to child processes and de- 
scendants of those child processes. 

If an invalid process ID or a process ID that is not a descendant 
process is specified, ERROR_NO_SIGNAL_SENT is returned. 

If the target process is a 16-bit process that has a signal handler set 
to ignore signals, ERROR_SIGNAL_REFUSED is returned. 





DosSetSignalExceptionFocus Signal Exceptions 


Sets or unsets the calling process as the receiving process for signal ex- 
ceptions for the session. 


SYNTAX 

APIRET DosSetSignalExceptionFocus(BOOL32 /32Focus, PULONG 
pulNestingLevel) 

PARAMETERS 


f32Focus - input 
Specify whether signal exception focus should be set or unset as fol- 
lows: 


Constant Description 

SIG_UNSETFOCUS Q Unset signal exception focus for the 
calling process. 

SIG_SETFOCUS 1 Set signal exception focus for the calling 
process. 


pulNestingLevel - output 
The address of a ULONG to receive the nesting level of the signal ex- 
ception focus for the calling process. 


RETURNS 
0 NO_ERROR 303 ERROR_INVALID_ 
PROCID 
1 ERROR_INVALID_FUNCTION 650 ERROR_NESTING_ 
TOO_DEEP 


300 ERROR_ALREADY_RESET 
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OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 378 DLL: DOSCALLS 

SEE ALSO 


DosAcknowledgeSignalException -42, DosEnterMustComplete -46, 
DosExitMustComplete -47, DosRaiseException -36, 
DosSendSignalException -43, DosSetExceptionHandler -38, 
DosUnsetExceptionHandler -39, DosUnwindException -40 


NOTES 


Each call to this function with /32Focus parameter set to SIG_SETFO- 
CUS increments the focus count for the calling process by 1, and every 
call to this function with the flag set to SIG_LUNSETFOCUS decre- 
ments the count by 1. When this value is greater than 0, the process will 
receive any signal exceptions sent to it. If the process is one of many in 
a session (a.k.a. screen group) then the last process to invoke this func- 
tion will be the one to receive the signal exceptions. 

Presentation Manager programs cannot receive the signal excep- 
tion focus. If a PM program calls DosSetSignalExceptionFocus, ER- 
ROR_INVALID PROCID will be returned. 

If a program attempts to set itself as the signal exception focus and 
it already has a nesting level of 65535, then ERROR_NESTING_ TOO_ 
DEEP is returned and the nesting level remains 65535. Conversely, if the 
nesting level is 0, and an attempt is made to unset the signal exception 
focus, ERROR ALREADY RESET is returned. 

If a value other than 0 or 1 is specified for /62Focus, then ER- 
ROR_INVALID FUNCTION is returned. 


RESTRICTIONS/WARNINGS 


@ Even if there is no exception handler registered by the calling 
thread, this call will return NO_ERROR. 


Must-complete Functions 





DosEnterMustComplete enters a must-complete section of code that 
cannot be interrupted by asynchronous exceptions (pg. 46). 
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DosExitMustComplete exits a must-complete section of code (pg. 47). 





@ DosEnterMustComplete Must-complete 


Begins a section of code that holds asynchronous exceptions for the 
calling thread. 


SYNTAX 
APIRET DosEnterMustComplete (PULONG pulNestingLevel) 


PARAMETERS 


pulNestingLevel - output 
The address of a ULONG to receive the level of nesting of must-com- 
plete requests. 


RETURNS 

0 NO_ERROR 650 ERROR_NESTING_TOO_DEEP 

OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 380 DLL: DOSCALLS 

SEE ALSO 


DosExitMustComplete -47, DosGetInfoBlocks -278 


NOTES 


A must-complete section of code will not be interrupted by any asyn- 
chronous exceptions (including signal exceptions and asynchronous 
exceptions generated from within the must-complete section). Any 
asynchronous exceptions that occurred while the thread was inside the 
must-complete section will be dispatched when the must-complete sec- 
tion has ended (the nesting level is 0). 

A thread can determine its nesting level by calling DosGetInfo- 
Blocks and examining the tib2_usMCCount member of the TIB2 
structure. 

If the nesting level would exceed 65535, the nesting level is kept at 
65535, and the call returns ERROR NESTING_TOO_DEEP. 
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See the “Must-complete” section of the chapter introduction for 
information on how to defer synchronous exceptions with must-com- 
plete sections. 





DosExitMustComplete Must-complete 


Exits a must-complete section of code for the calling thread. 


SYNTAX 
APIRET DosExitMustComplete (PULONG pulNestingLevel) 


PARAMETERS 


pulNestingLevel - output 
The address of a ULONG to receive the must-complete nesting level 
for the calling thread. 


RETURNS 

QO NO_ERROR 300 ERROR_ALREADY_RESET 

OTHER INFO 

Include file: bsedos.h and bsexcpt.h Define: INCL_DOSEXCEP- 
TIONS 

Ordinal: 381 DLL: DOSCALLS 

SEE ALSO 


DosEnterMustComplete -46, DosGetInfoBlocks -278 


NOTES 


This call marks the end of a must-complete section of code for the call- 
ing thread and decrements the nesting count by one. When the nest- 
ing count reaches zero, any asynchronous exceptions that were held 
while the thread was inside the must-complete section will be dis- 
patched. 

A thread can determine its nesting level by calling DosGetInfo- 
Blocks and examining the tib2_usMCCount member of the TIB2 
structure. 

If the nesting level is already zero when this call is made, ER- 
ROR ALREADY _ RESET is returned. 
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Exception Handling Structures 





ContextFlags (ULONG) 0 
The ContextFlags field indicates the type of information that is returned for the remainder 
of the fields in this structure. 


Constant Items Returned 
CONTEXT _ CONTROL 0x01 EBP, CS:EIP, EFLAGS, SS:ESP 


CONTEXT_INTEGER 0x02 EAX, EBX, ECX, EDX, ESI, EDI 
CONTEXT_SEGMENTS 0x04 DS, ES, FS, GS 

CONTEXT FLOATING POINT 0x08 Numeric coprocessor state 
CONTEXT_FULL Oxl15 All of the above 


ctx_env[7] (ULONG) 4 
Coprocessor state. 

ctx_stack[8] (FPREG) 32 
Coprocessor stack registers. 

ctx_SegGs (ULONG) 112 
The GS extra segment. 

ctx_SegFs (ULONG) 116 


The FS extra segment. 


ctx_SegEs (ULONG) 120 
The ES extra segment. 


ctx_SegDs (ULONG) 124 
The data segment. 

ctx_RegEdi (ULONG) 128 
The destination index register. 


ctx_RegEsi (ULONG) 132 
The source index register. 

ctx_RegEax (ULONG) 136 
The EAX register. 


ctx_RegEbx (ULONG) 140 
The EBX register. 


ctx_RegEcx (ULONG) 
The ECX register. 


ctx_RegEdx (ULONG) 
The EDX register. 


ctx_RegEbp (ULONG) 
The base pointer. 


ctx_RegEip (ULONG) 


The instruction pointer. 


ctx_SegCs (ULONG) 


The code segment. 


ctx_EFlags (ULONG) 
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The EFLAGS register. This register may contain the following flags: 


Bit 
0 


Oo CO NN DD oO WB OO FDO 


pm fd 
= & 


12 & 13 
14 
Lp 
16 
7 
18 


144 
148 
152 
156 
160 
164 
Description 

Carry flag. 

Not used. 

Parity flag. 

Not used. 

Auxiliary carry flag. 

Not used. 

Zero flag. 

Sign flag. 

Trap flag. 


Interrupt-enable flag. 
Direction flag. 
Overflow flag. 

IOPL flag. 

Nested task flag. 

Not used. 

Resume flag. 

Virtual mode flag. 


Alignment check flag. 
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ctx_RegEsp (ULONG) 168 
The stack pointer. 
ctx_SegSs (ULONG) 172 


The stack segment. 


Used by: Passed into exception handlers. 





losig (ULONG) 0 
The low doubleword of the significand. 

hisig (ULONG) 4 
The high doubleword of the significand. 

signexp (USHORT) 8 


The low 15 bits is the exponent, and the 16th bit is the sign. 
Used by: CONTEXTRECORD structure. 





prev_structure (PEXCEPTIONREGISTRATIONRECORD ) 0 


A pointer to the previous exception registration record. This is set to NULL for registering 


exception handlers. 


ExceptionHandler (_ERR *) 4 


The address of the exception handler to be registered. 


Used by: DosSetExceptionHandler -38, DosUnsetExceptionHandler -39, 
DosUnwindException -40 





ExceptionNum (ULONG) 0 
The exception number. This can be either a system-defined exception value or a user-de- 
fined exception value. See “System Defined Exceptions.” 


Exceptions 


fHandlerFlags (ULONG) 4 
The following flags may be found/specified: 


Constant Description 


EH _NONCONTINUABLE 0x01 The exception is a noncontinuable excep- 
tion and the thread must be terminated. 


EH_UNWINDING Qx02 An unwind operation is in progress. The ex- 
ception handler will be unwound. 


EH_EXIT_UNWIND Qx04 An exit unwind operation is in progress. All 
exception handlers for the thread will be un- 
wound and the thread will be terminated. 


EH_STACK_ INVALID 0x08 The stack is unaligned or the stack has ex- 
ceeded its boundaries. The thread will be 
terminated. 

EH_NESTED_CALL Oxl0 ‘The exception handler is being called due to 


an exception that occurred while an excep- 
tion was being processed by an exception 
handler (a nested exception). 


NestedExceptionReportRecord (PEXCEPTIONREPORTRECORD) 8 
A pointer to a nested exception report record. This is the pointer to the exception report 
record that was passed into the previous exception. This field is only set when a nested ex- 
ception occurs. 


ExceptionAddress (PVOID) 12 
The instruction address where the exception occurred. 

cParameters (ULONG) 16 
The size, in bytes, of the filled-in ExceptionInfo. 
ExceptionInfo[EXCEPTION_MAXIMUM_PARAMETERS] (ULONG) 20 


The information specific to this exception. 


Used by: DosRaiseException -36, DosUnwindException -40, 
Exception handler routines -39 


Exception Handler Information 





Exception handlers must have the following prototype: 
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ULONG APIENTRY MyHandler (PEXCEPTIONREPORTRECORD, 
PEXCEPTIONREGISTRATIONRECORD, 
PCONTEXTRECORD, PVOID) 


The following values may be returned by an exception handler: 
Constant Description 


XCPT_CONTINUE_SEARCH 0x00000000 The exception was not han- 
dled. The exception is passed 
down the chain. 


XCPT_CONTINUE_EXECUTION = OxFFFFFFFF The exception was handled. 
The exception will not be 
passed down the chain. 


XCPT_CONTINUE_STOP 0x00716668 The exception was handled by 
the debugger (via DosDebug). 


System Defined Exceptions 





Exception codes have the following format: 


SoLPPRPPPPRRR FRE FRPCCCCCCCCCCCCCCCe 


SS bits 
The severity code. The severity codes are defined as follows: 
Value Description 
00 Success 
Ol Informational 
10 Warning 
1] Error 
T bit 
The customer code flag. 
F bits 


The facility code. All exceptions that are OS/2 2.x-specific have a facility code of 1. 


C bits 
The facility’s status code. 


Nonfatal Software-generated Exceptions 


Constant 


XCPT_GUARD_PAGE_ VIOLATION 


ExceptionInfo[0] - Access flags: 


Access Flags 


XCPT_READ_ACCESS 0x1 
XCPT_WRITE_ACCESS 0x2 
ExceptionInfo[1] - The fault address. 
XCPT_UNABLE_TO_GROW_STACK 


Fatal Software-generated Exceptions 


Constant 


XCPT_IN_PAGE_ ERROR 


Exceptions 


Description 


A committed guard page 
has been accessed. The de- 
fault system processing is to 
strip the guard page at- 
tribute and commit and 
mark the previous page as a 
guard page. 


The system was unable to 
commit and mark the pre- 
vious page as a guard page. 


Description 


0xC0000006 An attempt was made to 


read a page into memory 
and an I/O error occurred. 


ExceptionInfo[0] - The address within the page being read. 


XCPT_PROCESS_ TERMINATE 


XCPT_ASYNC_PROCESS _ 
TERMINATE 


0xC0010001 A thread called DosExit on 


itself or the entire process, 
or the thread did not han- 
dle a fatal exception. 


Another thread in the 
process called DosExit for 
the process, or a fatal ex- 
ception that occurred in 
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ExceptionInfo|0] - The TID of the terminator thread. 


XCPT_NONCONTINUABLE _ 0xC00000024 
EXCEPTION 


XCPT_INVALID_DISPOSITION 0xC00000025 


XCPT_INVALID_LOCK_SEQUENCE 0xC0000001D 


XCPT_UNWIND 0xC00000026 


XCPT_BAD_STACK 0xC00000027 


XCPT_INVALID_UNWIND_TARGET 0xC00000028 


XCPT_SIGNAL 0xC00100003 


another thread was not 
handled. 


An exception handler re- 
turned XCPT_ CONTIN- 
UE_EXECUTION to a non- 
continuable exception. 


An exception handler re- 
turned a value other than 
XCPT_CONTINUE_EXE- 
CUTION or XCPT_CON- 
TINUE_SEARCH. 


An attempt was made to ex- 
ecute an operation within 
an interlocked section of 
code, and the sequence is 
invalid for the host ma- 
chine architecture. 


The exception handler is 
being unwound. 


This exception occurs when 
either an exception regis- 
tration record is not prop- 
erly aligned on the stack, 
the record exceeds the stack 
boundaries, or an unwind 
target is specified that does 
not point to an exception 
report record. 


An attempt was made to un- 
wind an exception report 
record that has an address 
below the current stack 
pointer. 


The process received a sig- 
nal. This exception is only 


Exceptions 


received by handlers regis- 
tered for thread 1. 


ExceptionInfo[0] - The signal number. The following values are system defined sig- 


nals: 


Constant 


XCPT_SIGNAL_INTR 


XCPT_SIGNAL_KLLPROCG 
XCPT_SIGNAL_ BREAK 


Fatal Hardware Exceptions 


Constant 


XCPT_ACCESS VIOLATION 


Value 


Description 


1 Ctrl-C 
3 DosKillProcess 
4 Ctrl - break 


Description 


QxC0000005 An attempt was made to access 


ExceptionInfo[0] - Access attempted: 


Access Flags 


XCPT_UNKNOWN_ACCESS 


XCPT_READ_ ACCESS 
XCPT_WRITE_ACCESS 


XCPT_EXECUTE_ACCESS 


XCPT_SPACE ACCESS 


0x0 
Ox] 
Ox2 
Ox4 
0x10 


an uncommitted page or to ac- 
cess a page without the correct 
access permissions. See Intel 
documentation for information 
on Interrupt 13 and Interrupt 
14 for more information on the 
causes of this exception. For an 
Interrupt 13, the IP in the Ex- 
ceptionAddress field of the EX- 
CEPTIONREPORTRECORD 
will be the address of the in- 
struction that caused the fault to 
occur. 
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ExceptionInfo[1] - The address of the data on which an access was attempted, or 


XCPT_DATA_UNKNOWN. 
XCPT_INTEGER_DIVIDE_ 
BY_ZERO 


XCPT_FLOAT_DIVIDE_ 
BY ZERO 


XCPT_FLOAT_INVALID_ 
OPERATION 


XCPT_ILLEGAL 
_INSTRUCTION 


XCPT_PRIVILEGED_ 
INSTRUCTION 


XCPT_INTEGER_OVERFLOW 


XCPT_FLOAT_OVERFLOW 


XCPT_FLOAT_UNDERFLOW 


OxCO000009B 


0xC00000095 


0xC00000097 


OxC0000001C 


0xC0000009D 


O0xC0000009C 


0xC00000098 


OxCO000009A 


An attempt was made to divide 
an integer dividend by an inte- 
ger zero divisor. 


An attempt was made to divide a 
floating point dividend by a zero 
floating point divisor. 


Either a stack fault occurred or 
there was an invalid operation 
according to IEEE Std 754. 


An attempt was made to execute 
an instruction not supported by 
the host machine architecture. 


An attempt was made to execute 
an instruction that is not per- 
mitted by the current machine 
mode. 


An attempt was made to per- 
form an integer operation that 
would cause the carryout of the 
most significant bit of the result 
to be different from the carry- 
into of the most significant bit. 


An attempt was made to per- 
form a floating point operation 
that would result in the expo- 
nent exceeding the magnitude 
of the largest finite number sup- 
ported by the respective floating 
point data type. 


An attempt was made to per- 
form a floating point operation 
that would cause the result of 
the operation to be different 
from what would have been 
computed had the exponent 
and component range been un- 
bounded. 
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XCPT_FLOAT_DENORMAL_ QxC00000094 An attempt was made to per- 

OPERAND form a floating point operation 
on a denormal operand when 
the program had not masked 
off denormal operations. 


XCPT_INEXACT_RESULT 0xC00000096 A floating point operation was 
attempted that would produce a 
result that was not exactly repre- 
sentable in the destination for- 
mat. 


XCPT_FLOAT_STACK CHECK  0xC00000099 The floating point processor at- 
tempted an illegal operation on 
a private stack. 


XCPT_DATATYPE _ OxCO000009E An attempt was made to load or 

MISALIGNMENT store data in an address that is 
not naturally aligned on a hard- 
ware architecture that does not 
provide alignment hardware. 


ExceptionInfo[0] - Access attempted: 


Access Flags 
XCPT_READ_ACCESS Oxl 
XCPT_WRITE_ACCESS Ox2 


ExceptionInfo|1] - Data type mask that indicates how many low bits must be zero. For 
16-bit entities it is 1, and for 32-bit entities it is 3. 


ExceptionInfo| 2] - The virtual address of the misaligned data. 


XCPT_BREAKPOINT OxCOQ000009F A breakpoint instruction was ex- 
ecuted. This exception is for de- 
buggers only. 

XCPT_SINGLE_STEP OxCOO00000A0 A trace trap occurred, or some 


other single instruction mecha- 
nism signaled that one instruc- 
tion executed. 
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S/2 provides a standard set of file management functions that in- 
clude file opening, creating, reading, writing, copying, moving, 
deleting, region locking, and attribute manipulation. Additionally, 
functions are provided for directory management. All file manage- 
ment functions work seamlessly across file systems. However, some file 
systems will not support certain functions. 
Applications inherit the current drive directory of the application 
that started them, and all file management functions will operate from 
the perspective of the current drive and directory. 


File Handles 


When an application opens a file using DosOpen, the system will 
return a 32-bit file handle that refers to that file. The file handle re- 
turned by DosOpen should not be confused with the file pointers 
returned by the C library functions such as fopen( ). They are differ- 
ent types and cannot be used interchangeably. 

Each process has a maximum number of file handles that may be 
allocated. This number is normally 20, but some programs can change 
the system default to a higher value via an undocumented interface. 
Applications may change the maximum number of file handles for 
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their process by calling either DosSetMaxFH or DosSetRelMaxFH. 
Child processes inherit all of the open file handles of their parents. 
Therefore, it is important for applications that will need to keep nu- 
merous files open simultaneously to use DosSetRelMaxFH to ensure 
they will have enough file handles available. 

Applications started by the command processor will have access to 
standard input, standard output, and standard error with file handles 
0, 1, and 2 respectively. Applications need not open the standard I/O 
files to begin using them. 

Applications can create duplicate file handles of open files by call- 
ing DosDupHandle. The duplicate handle will have a different value, 
but will represent the same file as the original. Additionally, the han- 
dles reference the same file pointer so that I/O operations stay in sync. 
Typically, DosDupHandle is used in conjunction with DosCreatePipe 
to redirect the standard input and standard output of child processes. 
See Chapter 10, “Pipes” for more information on redirecting a child 
processes standard I/O. 


Protected File Handles 


OS/2 provides an analogous set of file management APIs that work 
with protected file handles. Protected file handles guard applications 
from errant threads that might corrupt files by using file handles that 
they were not meant to use. The protection is implemented in the 
form of a key that is returned when a call to DosProtectOpen is made. 
This key must be used on subsequent file management APIs in order 
to perform file I/O. Additionally, the system will not allow circumven- 
tion of the protection by applications attempting to call the standard 
file management APIs with protected file handles. DosDupHandle is 
not allowed with protected file handles, as this would nullify the pro- 
tection that these protected file handles provide. 

An example of the use of protected file handles is the need to 
write a database DLL that is linked to by client applications, where the 
implementer of the database DLL would want to protect its file I/O 
from errant threads within the client application by using protected 
file handles. Otherwise, a thread within an application could begin 
writing to a file handle that it does not belong to it. Since this applica- 
tion is working with a database, this could cause the database to be- 
come corrupted. 
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File Pointers 


File pointers are used to indicate which byte of a file will be read from or 
written to by the next I/O operation. The system sets the file pointer to 
the beginning of the file when it is first opened. As I/O operations are 
performed on the file, the pointer is advanced accordingly. 

Applications can change the location to which the file pointer 
points by calling DosSetFilePtr. When an application reaches the end 
of a file and attempts to read, no error is returned and a value of zero 
is returned for the number of bytes read. ‘This is how the system indi- 
cates the end of file (EOF) condition. 

Writing data to a file causes the data to be transferred to an inter- 
nal buffer that only writes the data to disk when it is full, or the buffer 
is flushed by calling DosResetBuffer. The size of the internal buffer is 
that of one sector on the target disk or a multiple of one sector. The 
size of the buffer is configurable via the BUFFERS statement in CON- 
FIG.SYS. The system will automatically flush the buffers and update di- 
rectory information when the file is closed. 


File Region Locking 


Often, it is necessary for more than one process to work simultane- 
ously with a given file. OS/2 provides a simple mechanism for locking 
specific regions of a file without locking the entire file. DosSet- 
FileLocks allows an application to specify a range of bytes in a file that 
are locked and cannot be accessed by another process. DosSetFile- 
Locks is also used to unlock the range. An application that attempts to 
access a portion of a file that is locked will get an ERROR_LOCK_VI- 
OLATION return code. A region cannot overlap another locked re- 
gion or encompass another locked region. 

Although child processes inherit the open file handles of the par- 
ent, they do not inherit access to locked regions. The parent process 
must first duplicate the file handle containing the locks, and pass it to 
the child process, whereupon it has access to the locked regions. 

File locks are only intended to be used for a short period of time. 
When a file is closed, any locks that exist are released in no specific order. 


Metacharacters 


Metacharacters are wildcard characters that can be substituted for 
matching actual characters in a file name. OS/2 supports two meta- 
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characters: the asterisk (*) and the question mark (?). The following 
characteristics are defined for these metacharacters: 


Metacharacter Characteristics 


? Matches one character only (except the 
period or NULL) at a precise character 
position. 


May not be used to match or cross the 
backslash (\) character. 


- Matches one or more characters including 
blanks, but not the period. 


Will not match across cross the backslash (\) 
or NULL characters, therefore, entire paths 
cannot be matched. 


Metacharacters also take on different characteristics based on how 
they are used. When performing searches, the following rules should 
be considered: 


@ Any character, other than a metacharacter, matches itself. 

@ Searches are case-insensitive. 

@ Any file name that does not contain a period will have one implicitly 
appended to it during a search. This is for compatibility. 


Applications may wish to expand file names with metacharacters 
for their own use. DosEditName takes a source file name and a tem- 
plate file name that contains metacharacters and derives a new file 
name by expanding it. For example: 


@ Asource string of ABC.TXT and a template string (a.k.a edit string) 
of A*.DOC would result in a file name of ABC.DOC. 

@ A source string of ABC.DEF and a template string of APD.M* would 
result in a file name of ABD.MEF-. 

@ A source string of ABC?DEF.-TXT and a template string of ABCX- 
* CPY would result in a file name of ABCXDEF.CPY. 


Therefore, an application wishing to copy all files with the exten- 
sion .CPP to .BAK would: 


1. Search for all files with the .CPP extension using DosFindFirst/ 
DosFindNext. 
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2. Use DosEditName to transform the source file name using the tem- 
plate *.BAK. 
3. Call DosCopy using the new file name. 


The Command Processor and File Names 


Since file names on HPFS volumes may contain characters that are in- 
terpreted by the command processor in a special way, special charac- 
ters are used to prevent the command processor from misinterpreting 
user intentions. For example: By default, when invoking a program 
with arguments, the command processor passes each space-delimited 
string it finds as a separate argument. To pass an argument containing 
blanks as a single argument, the string should be prefixed and suffixed 
with double quotation marks (“). The caret is used to pass characters 
with special properties as arguments. For example, the command 
processor interprets the vertical bar (|) as a pipe command, so, to pass 
this character to a program, the vertical bar should be prefixed with a 
caret (I). : 


Devices 


The system treats devices as file streams, and therefore allows you to ac- 
cess those devices using calls such as DosOpen, DosRead, and 
DosWrite. For a description of the types of devices that may be ac- 
cessed in this way, see Chapter “File System” overview (pg. 141). 


Extended Attributes 


Extended Attributes (EAs) are user-definable attributes that are at- 
tached to either a file or directory. On HPFS volumes, the attributes 
are stored next to the file object on disk. On FAT volumes, the attri- 
butes for all the file objects on the volume are stored in a hidden file 
called EA DATA. SF. The file contains spaces to make it difficult to 
modify accidentally. 

Extended attributes can contain any type of data, such as binary or 
ASCII data. There are several formats that have already been defined 
by the system, and applications can create their own formats as well. 
See “Extended Attribute Data Types,” pg. 139 for a list of predefined 
data types. 
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Extended attributes can be queried with DosQueryFileInfo and 
DosQueryPathInfo, and set with DosSetFileInfo and DosSetPathInfo. 
Additionally, extended attributes can be returned on file searches with 
DosFindFirst/ DosFindNext. However, DosFindFirst/DosFindNext do 
not allow extended attributes to be a part of the search criterion. 


Restrictions and Warnings 


@ There is no documented API that provides the capability to monitor 
the occurrence of a particular activity on a file or directory. 

@ Extended attributes may not exceed 64k for a single file object. 

@ DosFindFirst/DosFindNext do not allow extended attributes to be a 
part of the search criteria. 


File Manipulation Functions 





DosCancelLockRequest cancels an outstanding lock request (see 
Appendix A). 

DosClose/DosProtectClose closes a file handle (pg. 64). 

DosCopy copies a file or subdirectory (pg. 65). 

DosDelete deletes a file (pg. 67). 

DosEditName performs metacharacter file name transformation 
(pg. 68). 

DosForceDelete deletes files so that they cannot be recovered with the 
OS/2 UNDELETE command (pg. 70). 

DosMove moves a file or subdirectory within the same volume 
(pg. 71). 

DosOpen/DosProtectOpen opens a file, pipe, or device (pg. 73). 
DosReadDosProtectRead reads data from a file, pipe, or device 
(pg. 79). 

DosSetFileInfo/DosProtectSetFileInfo sets file information for an 
open file (pg. 80). 

DosSetFileLocks/DosProtectSetFileLocks locks or unlocks a range of 
bytes within a file (pg. 82). 

DosSetFilePtr/DosProtectSetFilePtr sets the position of the file 
pointer (pg. 84). 
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DosSetFileSize/DosProtectSetFileSize changes the size of a file 
(pg. 86). 

DosSetPathInfo sets information on a file or device (pg. 87). 
DosSetVerify enables or disables write verification (pg. 89). 
DosWrite/DosProtectWrite writes data to a file, pipe, or device (pg. 90). 





DosClose/DosProtectClose File Management 





Closes a named or unnamed pipe. 


SYNTAX 


APIRET DosClose (HFILE h/File) 
APIRET DosProtectClose (HFILE hfFile, FHLOCK /hl/d) 


PARAMETERS 

hfFile - input 

The handle of a file, device, or pipe. 

fhild - input 

The file handle lock ID that was returned from a call to Dos- 
ProtectOpen. 


RETURNS 

0 NO_ERROR 5 ERROR _ ACCESS DENIED 
2 ERROR_FILE_NOT_FOUND 6 ERROR INVALID HANDLE 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 257 DLL: DOSCALLS 

SEE ALSO 


DosDupHandle -91, DosOpen -73, DosResetBuffer -92-A 


NOTES 


If there are any duplicate file handles created for a file, they must be 
closed before the directory information and internal file buffers are 
flushed. 

When appropriate, closing a device handle causes the device to be 
notified of the close. 
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@ DosCopy File Management 


Copies a file or subdirectory. 


SYNTAX 

APIRET DosCopy(PSZ pszSourceName, PSZ pszTargetName, ULONG 
ulOpiions) 

PARAMETERS 


pszSourceName - input 

A null-terminated string containing the name of the file, subdirectory, 
or character device to copy. Global file name characters (a.k.a. wild- 
card characters) are not allowed. 

pszTargetName - input 

A null-terminated string containing the name of the target file, subdi- 
rectory, or character device. Global file name characters (a.k.a. wild- 
card characters) are not allowed. 

ulOptions - input 

Specify the following copy options: 


Options Description 


DCPY_EXISTING 0x01 Copy the source file/directory to the target 
even if there is already a file/directory with 
the same name in the target directory. If this 
flag is not specified, the copy will not occur 
if the file/directory already exists, and an 
error will be returned. 


DCPY_APPEND Qx02 When copying a file, append the source to 
the target if it already exists. If this flag is not 
specified, the copy will replace the target if it 
exists. 


DCPY_FATLEAS 0x04 Return an error if the target file-system does 
not support EAs. If this flag is not specified, 
the EAs will be discarded if the target file 
system does not support them. 
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RETURNS 


0 NO_ERROR 87 ERROR_INVALID_ 
PARAMETER 

2 ERROR_FILE_NOT_FOUND 108 ERROR_DRIVE_LOCKED 

3 ERROR_PATH_NOT_FOUND 112 ERROR_DISK_FULL 

4 ERROR _TOO_MANY_ 206 ERROR_FILENAME_EXCED 
OPEN_FILES _RANGE 

5 ERROR_ACCESS_ DENIED 267 ERROR_DIRECTORY 

26 ERROR_NOT_DOS_DISK 282 ERROR_EAS NOT_ 


SUPPORTED 
32 ERROR SHARING _ 283 ERROR NEED _ EAS | 
VIOLATION FOUND 
36 ERROR SHARING BUFFER EXCEEDED 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 258 DLL: DOSCALLS 
SEE ALSO 


DosDelete -67, DosMove -71, DosQueryCurrentDir -124, 
DosQueryCurrentDisk -125 


NOTES 


DosCopy takes the following actions when an I/O error occurs: 


@ If pszSourceName is a subdirectory, then the file being copied is 
deleted from the target path. 

@ If pszTargetNameis a file to be replaced, then the file is deleted from 
the target path. 

@ If pszTargetName is a file to be appended, then the target file is re- 
stored to its original size. 


If the target of a copy operation is in use (open), then ERROR_ 
SHARING_VIOLATION is returned unless no options were specified, 
in which case, ERROR ACCESS _ DENIED is returned. 

If the target of the copy operation is a device, then the source 
must be a file. Additionally, the DCPY_APPEND and DCPY_EXISTING 
attributes are ignored. 

If an attempt is made to copy a directory to a single file, error ER- 
ROR_ DIRECTORY is returned. 
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File object attributes (date and time or creation attributes) are al- 
ways copied from the source to the target of a copy; however, extended 
attributes are only copied when creating a new file or directory, or 
when replacing a file or directory. 

If a source file being copied has a “need” EA and the target file sys- 
tem does not support EAs, then an error is returned regardless of 
whether DCPY_FAILEAS was specified. 


Append Operations (DCPY_APPEND specified) 


Note: The DCPY_APPEND option is ignored when copying a directory, or copying to 
a file that does not exist. 


Target Attributes Result 
None, Archive, Hidden, or System Append performed successfully. 


Read Only Append fails with an 
ERROR_ACCESS_ DENIED error. 


Existing Operations (DCPY_EXISTING specified) 
Note: This option applies to both target files and directones. 


Target Attributes Result 
None or Archive Copy performed successfully. 
Hidden, System, or Read-only Copy fails with an ERROR_ 


ACCESS_DENIED error. 





DosDelete File Management 


Deletes a file. 


SYNTAX 
APIRET DosDelete(PSZ pszFilename) 


PARAMETERS 

pszFilename - input 

The address of a null-terminated string containing the name of the file 
to be deleted. 
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RETURNS 


0 NO_ERROR 32 ERROR_SHARING_ 
VIOLATION 

2 ERROR_FILE_NOT_FOUND 36 ERROR SHARING_ 
BUFFER EXCEEDED 

3 ERROR_PATH_NOT_FOUND 87 ERROR_INVALID_ 
PARAMETER 

5 ERROR_ACCESS_DENIED 206 ERROR_FILE NAME_ 
EXCED_RANGE 

26 ERROR_NOT_DOS_DiSK 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 259 DLL: DOSCALLS 

SEE ALSO 


DosCopy -65, DosDeleteDir -123, DosForceDelete -70, DosMove -71 


NOTES 


Files that have the read-only attribute cannot be deleted by DosDelete. 
Files with any other file attributes may be deleted. DosSetPathInfo may 
be used to change the file’s attributes. 

Files deleted with DosDelete might be recoverable with the OS/2 
UNDELETE command. See the OS/2 on-line documentation on UN- 
DELETE for more information. 

DosDelete cannot delete directories; instead, use DosDeleteDir. 





@® DosEditName File Management 


Transforms a path name containing metacharacters into a non meta- 
character pathname. 


SYNTAX 

APIRET DosEditName(ULONG ulEditLevel, PSZ pszSourceString, PSZ 
pszEditString, PBYTE pbResuliBuf, ULONG 
ulResultBufLen) 
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PARAMETERS 


ulEditLevel - input 

The level of editing semantics to use for performing the transforma- 
tion. A value of 1 must be specified (use OS/2 1.2 editing semantics). 

pszSourceString - input 

The address of a null-terminated string containing the string to be 
transformed. This string must only contain the component of the path 
to be transformed, not the complete path. If a complete path is speci- 
fied, an error will be returned. 

pszEditString - input 

The address of a null-terminated string containing the string to be 
used for editing. Any metacharacters (wildcards) will be interpreted as 
editing characters. This string must not include the path information. 
pbResultBuf - output 

The address of a buffer that will receive the null-terminated string of 
the resulting transformation. 

ulResultBufLen - input 

The length, in bytes, of the result buffer pointed to by pbResultBuf. 


RETURNS 

0 NO_ERROR 123 ERROR_INVALID NAME 
87 ERROR_INVALID_PARAMETER 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 261 DLL: DOSCALLS 

SEE ALSO 


DosCopy -65, DosDelete -67, DosForceDelete -70, DosMove -71 


NOTES 


DosEditName is used to transform file names/subdirectories into a dif 
ferent file name/subdirectory by taking the value specified in psz- 
EditString and overlaying it on pszSourceString. Any explicit characters 
specified in the edit string are overlayed on the source string and 
placed in the result string, but metacharacters are treated as follows: 


* The asterisk copies one or more characters from the source to the 
result string until it finds a character in the source string that 
matches a character in the edit string. 
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The question mark copies a single character from the source to 
the result string, except a period, in which case no character is 
copied. 

The period synchronizes the source pointer and result pointer to 
match each other in character position. 


If no period (.) is specified in the edit string, then none will be added 
to the result string. 

Matching is not case-sensitive, but the result is case-preserved. If 
there is a conflict between the case of the source string and edit string, 
then the case of the edit string is used. 


RESTRICTIONS/WARNINGS 


@® Specifying any kind of path information in either the source or edit 
string such as a backslash (\), or colon (:) will result in ERROR_IN- 
VALID_NAME error being returned. 





DosForceDelete File Management 


Deletes a file so that it is not recoverable with the OS/2 UNDELETE 
command. 


SYNTAX 
APIRET DosForceDelete(PSZ pszFilename) 


PARAMETERS 

pszFilename - input 

The address of a null-terminated string containing the name of the file 
to be deleted. 


RETURNS 


0 NO_ERROR 32 ERROR_SHARING_ 
VIOLATION 

2 ERROR_FILE_NOT_FOUND 36 ERROR_SHARING_ 
BUFFER_EXCEEDED 

3 ERROR PATH NOT_FOUND 87 ERROR_INVALID_ 
PARAMETER 

5 ERROR_ACCESS_ DENIED 206 ERROR_FILENAME _ 
EXCED_RANGE 

26 ERROR_NOT_DOS_DISK 
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OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 110 DLL: DOSCALLS 

SEE ALSO 


DosCopy -65, DosDelete -67, DosDeleteDir -123, DosMove -71 


NOTES 


OS/2 systems configured to save deleted files (via the DELDIR state- 
ment) will see a performance improvement when DosForceDelete is 
used instead of DosDelete. Files deleted with DosForceDelete are not 
recoverable with the OS/2 UNDELETE command since no backup of 
the file is made. See the OS/2 on-line documentation on UNDELETE 
for more information. 

Files that have the read-only attribute cannot be deleted by 
DosForceDelete. Files with any other file attributes may be deleted. 
DosSetPathInfo can be used to change the file attributes. 

DosDelete cannot delete directories; use DosDeleteDir instead. 





DosMove File Management 


Moves a file or subdirectory within the same volume. Also, can be used 
to rename. 


SYNTAX 
APIRET DosMove (PSZ pszOldPath, PSZ pszNewPath) 


PARAMETERS 


pszOldPath - input 

The address of a null-terminated string containing the path of the file or 
subdirectory to move. Metacharacters (wildcards) are not permitted. 
pszNewPath - input 

The address of a null-terminated string containing the new path. The 
new path must be on the same volume as the old path. For file moves, 
the new path must contain the file name component. 


RETURNS 


OQ NO_ERROR 32 ERROR _SHARING_ 
VIOLATION 
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2 ERROR FILE _NOT_FOUND 36 ERROR_SHARING_ 
BUFFER_EXCEEDED 

3 ERROR_PATH_NOT_FOUND 87 ERROR_INVALID_ 
PARAMETER 

4 ERROR_TOO_MANY_ 108 ERROR_DRIVE_LOCKED 

OPEN_FILES 

5 ERROR ACCESS DENIED 206 ERROR_FILENAME_ 

EXCED_RANGE 


17 ERROR _ NOT_SAME_ 250 ERROR CIRCULARITY_ 
DEVICE REQUESTED 

19 ERROR WRITE PROTECT 251 ERROR DIRECTORY _ 
IN_CDS 

26 ERROR NOT _DOS_DISK 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: DiI DLL: DOSCALLS 

SEE ALSO 


DosCopy -65, DosDelete -67, DosDeleteDir -123, DosForceDelete -70, 
DosQueryCurrentDisk -125, DosSetDefaultDisk -127 


NOTES 


DosMove can be used to rename files or subdirectories, including chang- 
ing the case of the name (for example, myfile.tmp to MyFile.T'mp). 

A drive name may be specified in the old and new path arguments, 
but the drive letter must be the same. An attempt to move to a differ- 
ent drive will result in an ERROR _NOT_SAME_DEVICE error. 

An attempt to move a parent directory to one of its descendant di- 
rectories will result in an ERROR_CIRCULARITY_REQUESTED error 
(or ERROR_ACCESS_DENIED if it involves the current directory of 
the process). 

Any attributes and EAs that are associated with the file or directory 
will be moved with it. 

ERROR_ACCESS_DENIED will be returned if there is an attempt 
to move a file to a directory where there is a file with the same name 
and the read-only attribute is set. 

ERROR_TOO_MANY_OPEN_FILES will be returned if the sys- 
tem cannot allocate any file handles to perform the move operation. 
See DosSetRelMaxFH, pg. 99, and DosSetMaxFH, pg. 98, for more in- 
formation. 
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RESTRICTIONS/WARNINGS 


@ Do not confuse the syntax of DosMove with the OS/2 MOVE com- 
mand. For file move operations, the pszNewPath argument must in- 
clude the file name component. 





DosOpen/DosProtectOpen File Management 


Opens a new or existing file, a named pipe, or a device. 


SYNTAX 


APIRET DosOpen(PSZ pszFileName, PHFILE phfFileHandle, PULONG 
pulActionlaken, ULONG ulFileSize, ULONG u/lFile- 
Attribute, ULONG ulOpenOption, ULONG ulOpen- 
Mode, PEAOP2 pEABu/f) 

APIRET DosProtectOpen(PSZ pszfileName, PHFILE phfFileHandle, 
PULONG pulActionTaken, ULONG 
ulFileSize, ULONG ulFileAtinbute, VULONG 
ulOpenOption, ULONG ulOpenMode, 
PEAOP2 pEABuf, PFHLOCK pfhild) 


PARAMETERS 

pszFileName - input 

A pointer to a buffer containing the null-terminated name of the file, 
pipe, or device to open. 

phfFileHandle - output 

The address of an HFILE that will receive the file handle. 
pulActionTaken - output 

The address of a ULONG to receive the action taken. You may not 
specify a NULL for this parameter. The following values may be re- 
turned: 


Constant Description 

FILE_EXISTED 1 The file already existed. 

FILE_CREATED 2 The file had to be created. 

FILE_ TRUNCATED 3 The file already existed, and was truncated 


to match the value specified for ulFileSize. 


For named pipes, this call always returns a value of FILE_EXISTED if 
the call was successful. 
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ulFileSize - input 

The new logical size (that is, the size of the data in the file) of the file, 
in bytes. This parameter is only used when creating or replacing an ex- 
isting file, and is ignored otherwise. If a file is being created or re- 
placed as a read-only file, this parameter must be set to zero. 
ulFileAttribute - input 

Specify the file attributes to be applied when a new file is being cre- 
ated. This field is ignored otherwise. The following attributes may be 
specified singularly or in combination by using the OR operator: 


Constant Description 
FILE_ARCHIVED 0x00000020 Set the archive attribute. 
FILE_DIRECTORY 0x00000010 The file is actually a subdirectory. 
FILE_SYSTEM 0x00000004 Set the system attribute. 


FILE_HIDDEN 0x00000002 Set the hidden attribute. The file will 
not appear in the directory listings. 


FILE_LREADONLY —0x00000001 Set the read-only attribute. 


FILE_NORMAL 0x00000000 The file may be read from and written 
to. This is merely the converse of the 
FILE_READONLY bit. 


ulOpenOption - input 
Specify one of the following open options: 


Constant Description 

OPEN _ACTION_FAIL IF NEW 0x00 Fail if the file does not 
already exist. 

OPEN _ACTION_FAIL IF EXISTS 0x00 Fail if the file already exists. 


OPEN _ACTION_OPEN_IF_EXISTS Ox01 Open the file if it already 
exists. 


OPEN_ACTION_REPLACE_IF_EXISTS 0x02 Replace the file if it already 
exists. 


OPEN ACTION _CREATE_JIF_ NEW QOxl0O Create the file if it does not 
exist. 


Specify FILE_OPEN or OPEN_ACTION_OPEN_IF_EXISTS for named 
pipes. 
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ulOpenMode - input 

The access mode must be the same as specified on the DosCreateNPipe 
call. The read mode and blocking mode are ignored. For read mode, 
it is set to whichever read mode was specified when the pipe was cre- 
ated; for blocking mode, it is set to block regardless of what was speci- 
fied when the pipe was created. The following mode options apply for 
named pipes (the default is in italics): 


Constant Description 


Open modes: 


OPEN_FLAGS_DASD 0x8000 The string pointed to by pszFile- 
Name actually is a drive letter (such 
as d:) that represents a mounted 
volume to be opened for direct 


access. 
OPEN _ FLAGS WRITE_ 0x4000 File accesses are to be handled 
THROUGH synchronously. The file writes may 


go through the system’s cache; 
however, the data will actually be 
written to disk before the call 
returns. This attribute is not 
inherited by child processes. 


OPEN FLAGS FAIL _ 0x2000 Media I/O errors should not be 

ON_ERROR reported via the system critical 
error handler, but reported to the 
caller via return code. This 
attribute is not inherited by child 
processes. Note: Media I/O errors 
that are generated as a result of a 
Category 8 IOCTL function are 
always reported via return code. 


OPEN_FLAGS_NO_CACHE = 0x1000 File I/O operations should not be 
routed through the file system 
driver’s cache. This attribute is not 
inherited by child processes. 
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Locality modes: 


Specify the method that describes most often how the file/device will be 


accessed. 


OPEN_FLAGS_NO_LOCALITY 0x0000 


OPEN_FLAGS_SEQUENTIAL 0x0100 


OPEN_FLAGS_RANDOM 0x0200 


OPEN_FLAGS _ 0x3000 
RANDOMSEQUENTIAL 


Inheritance: 


OPEN_FLAGS_NOINHERIT 0x0080 


The file is to be handled as if it has 
no locality. 


The file will be accessed mostly 
sequentially. 


The file will be accessed mostly via 
random access. 


The file will be accessed randomly, 
and then sequentially from these 
random points. 


The file handle cannot be inherited 
by child processes. 


Child processes normally can inherit this file handle unless this flag is set. 
The inheritance bit is not inherited by child processes. In other words, they 
must specify it so that it takes effect for their children. 


Sharing modes: 


Specify which types of accesses other processes should not have while the file 
is open. Sharing modes remain in effect until the process is closed or the 


process terminates. 


OPEN_SHARE_DENYREADWRITE 0x0010 No other process may open 


the file. 


OPEN_SHARE_DENYWRITE 0x0020 No other process may open 


the file for writing. 


OPEN_SHARE_DENYREAD 0x0030 No other process may open 


the file for reading. 


OPEN SHARE DENYNONE 0x0040 Deny neither read nor write 


access. 


Sharing modes are inherited by child processes inheriting the file handle. 
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Access modes: 


Specify which type of file access is desired. If another process has the file 
open and has restricted sharing privileges, then an access-denied error may 
be returned by the system. 


OPEN_ACCESS_READONLY 0x0000 Open the file for reading 
only. 

OPEN_ACCESS_WRITEONLY 0x0001 Open the file for writing only. 

OPEN ACCESS READWRITE 0x0002 Open the file for reading and 
writing. 


Access modes are inherited by child processes inheriting the file handle. 


pEABuf - input 

On input, the address of a buffer containing an EAOP2 structure or 
NULL if no EAs are to be created or modified. The /pFEA2List para- 
meter points to the data area containing the FEA2 list, which specifies 
the EAs to be created or modified. The fpGEA2List and oLrror parame- 
ters are ignored on input. EAs will only be set when a file is being cre- 
ated, or an existing file is being replaced or truncated. 

On output, fpFEA2List and the area it points to are unchanged; 
/pGEA2Listis left unchanged. If an error occurred while setting an EA, 
the oF7rror field will contain the offset of the FEA2 entry that caused the 
error, and a bad return code will be returned for the call. 
pfhild - output 
The address of an FHLOCK that will receive the protected file handle 
lock ID. 


RETURNS 


0 NO_ERROR 67 ERROR_BAD_NET_PATH 

2 ERROR_FILE_NOT_FOUND 82 ERROR_CANNOT_MAKE 

3 ERROR_PATH_NOT_FOUND 87 ERROR_INVALID_ 
PARAMETER 

4 ERROR_TOO_MANY_ 99 ERROR _DEVICE_IN_USE 

OPEN_FILES 

5 ERROR_ACCESS_DENIED 108 ERROR_DRIVE_LOCKED 

12 ERROR_INVALID_ACCESS 110 ERROR _OPEN_FAILED 

26 ERROR_NOT_DOS_DISK 112 ERROR_ERROR_ 
DISK_FULL 
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32 ERROR _SHARING_ 206 ERROR_FILENAME_ 
VIOLATION EXCED_RANGE 
36 ERROR _SHARING_ 231 ERROR_PIPE_BUSY 


BUFFER_EXCEEDED 
65 ERROR NETWORK _ 
ACCESS_DENIED 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 21D DLL: DOSCALLS 

SEE ALSO 


DosClose -64, DosConnectNPipe -234, DosCreateNPipe -235, 
DosDupHandle -91, DosQueryHType -95, DosRead -79, 
DosSetFileInfo -80, DosSetFilePtr -84, DosSetFileSize -86, 
DosSetMaxFH -98, DosSetRelMaxFH -99, DosSetNPHState -247, 
DosWrite -90 


NOTES 


Upon successful opening of the file, the file pointer will be set to the 
first byte of the file. The file pointer can be changed directly by calling 
DosSetFilePtr, and indirectly via DosRead and DosWrite. 

The wlFileSize parameter is treated as a recommendation. Even if 
the full size of the file cannot be allocated, the open may proceed nor- 
mally. When the size of a file is extended, the values of the data in the 
extended area are undefined. 

A replace operation is equivalent to atomically deleting and re- 
creating the file. Any EAs that are associated with the file will be 
deleted and re-created as well. 

When the file to be opened is actually a volume (the OPEN_ 
FLAGS_DASD option was used), direct access is provided to the entire 
volume, independent of the file system. The handle returned by 
DosOpen should be used to perform a DosDevIOCtl Category 8, 
Function 0 request to lock the volume. Subsequent Category 8 calls 
can then be used to manipulate the volume. After access to the volume 
is no longer needed, a DosDevIOCtl Category 8, Function 1 request 
should be made to allow other processes access to the volume again. 

DosOpen cannot be used to set volume labels on volumes, or to 
open volume labels. DosSetFSInfo should be used to set a volume 
label. 
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DosQueryHType can be used to determine if the handle returned 
represents a local or remote device, and what the type of the device is. 





DosRead/DosProtectRead File Management 


Reads the requested number of bytes from a file, pipe, or device. 


SYNTAX 


APIRET DosRead (HFILE hfFiledandle, PVOID pReadBuffer, VLONG 
ulReadBufferLen, PULONG pulBytesRead) 
APIRET DosProtectRead (HFILE hffiledandle, PVOID pReadBuffer, 
ULONG ulReadBufferLen, PULONG 
pulBytesRead, FHLOCK fhiLockId) 


PARAMETERS 

hfFileHandle - input 

The handle of the file, pipe, or device to read from. This handle must 
have been obtained from a call to DosOpen. 

pReadBuffer - output 

A pointer to a buffer that will receive the data read from the file, pipe, 
or device. 

ulReadBufferLen - input 

The length, in bytes, of the buffer pointed to by pReadBuffer. DosRead 
will attempt to read this number of bytes. 

pulBytesRead - output 

The address of a ULONG that will receive the actual number of bytes 
read. 

fhiLockld - input 

The file handle lock ID returned from a previous call to Dos- 
ProtectOpen. 


RETURNS 

0 NO_ERROR 26 ERROR NOT _DOS_DISK 

5 ERROR ACCESS DENIED 33° ERROR _LOCK_VIOLATION 
6 ERROR INVALID HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 


Ordinal: 281 DLL: DOSCALLS 
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SEE ALSO 
DosOpen -73, DosSetFilePtr -84, DosWrite -90 


NOTES 


For information regarding named pipes, see the named pipe specific 
description of this function on page 225. 

Applications cannot read past the end of the file. An attempt to do 
otherwise will cause DosRead to return less then the number of bytes 
requested. 

Read operations cause the file pointer referenced by h/FileHandle 
to be moved accordingly. 

It is not an error to request to read zero bytes. The system will just 
return NO_ERROR. 





DosSetFilelnfo/DosProtectSetFileinfo File Management 





Sets file information on an open file. 


SYNTAX 


APIRET DosSetFileInfo (HFILE h/fFile, ULONG ullnfoLevel, PVOID 
plnfoBut, ULONG ullnfoBufSize) 
APIRET DosProtectSetFileInfo (HFILE hfFile, ULONG ul/nfoLevel, 
PVOID plnfoBuf, ULONG ullnfo- 
BufSize, FHLOCK /fhiLockId) 


PARAMETERS 

hfFile - input 

A file handle. 

ullnfoLevel - input 

The type of information that will be set on the file. Specify one of the 
following: 


Constant Description 
FIL_ STANDARD 1 Date, time, or attribute information will be set. 


FIL_QUERYEASIZE 2 EAs will be set or cleared. 


plnfoBuf - input 


File Management 81 


The address of a buffer containing the information to be set. The for- 
mat of the buffer depends on the type of information being set as de- 
scribed: 


Level 1 Information 

A FILESTATUS3 structure containing the date, time, and attribute 
changes. For the date and time fields in the FILESTATUSS3 struc- 
ture, a value of zero causes no change to take place for those fields. 

On FAT file systems, only the last date and time can be modified. 
Creation and last-access date and time information can be specified, 
but will have no effect. 


Level 2 Information 

On input, an EAOP2 structure. The /pGEA2List field is ignored. 
/pFEA2List must point to a buffer containing the FEA2LIST. The 
FEA2s are the name/value pairs that are to be set. Each FEA2 must 
begin on a doubleword boundary. The oNexiEntryOffset field must 
contain the number of bytes from the begining of the current FEA2 
to the start of the next FEA2. The oNextkniryOffset field of the last 
FEH2 must be set to zero. The EA value must begin after the FEA2 
that is associated with it. The value must be in the format appropri- 
ate for its type. 

On output, nothing. The data on input is left unchanged unless there 
was an error, in which case, oErrorwill provide the offset to the FEA2 
that caused the problem. 


ullnfoBufSize - input 

The size, in bytes, of the buffer pointed to by plnfoBuf. 

fhiLockld - input 

The file handle lock ID returned from a previous call to DosProtect- 
Open. 


RETURNS 
0 NO_ERROR 122 ERROR_INSUFFICIENT_ 
BUFFER 
1 ERROR_INVALID_ 124 ERROR_INVALID_ LEVEL 
FUNCTION 


5 ERROR_ACCESS_DENIED 130 ERROR_DIRECT_ 
ACCESS_HANDLE 


6 ERROR_INVALID_ 254 ERROR_INVALID_ 
HANDLE EA_NAME 
87 ERROR_INVALID_ 255 ERROR_EA_LIST_ 


PARAMETER INCONSISTENT 
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OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 218 DLL: DOSCALLS 

SEE ALSO 


DosClose -64, DosEnumAttribute -101, DosOpen -73, 
DosQueryFileInfo -103, DosQueryPathInfo -106, 
DosResetBuffer -92-A, DosSetFileSize -86, DosSetPathInfo -87 


NOTES 


This call will work only on files that have been successfully opened 
for write access, and the sharing mode is set to Deny Both (see 
DosOpen -73). 

Last modification date and time are changed when a change is 
made to the EAs. 





DosSetFileLocks/DosProtectSetFileLocks File Management 





Locks or unlocks a range of bytes within a file. 


SYNTAX 


APIRET DosSetFileLocks(HFILE /A/fFile, PFILELOCK pflUnlockRange, 
PFILELOCK pflLockRange, ULONG wlTime- 
Out, ULONG wilFlags) 
APIRET DosProtectSetFileLocks (HFILE /h/fFile, PFILELOCK pflUnlock- 
Range, PFILELOCK pflLockRange, 
ULONG wlTimeOut, ULONG ulFlags, 
FHLOCK /hiLockld) 


PARAMETERS 

hfFile - input 

A file handle. 

pflUnlockRange - input 

The address of a FILELOCK structure (see pg. 136) that contains the 
offset and range of bytes to be unlocked (if any). 

pflLockRange - input 

The address of a FILELOCK structure (see pg. 136) that contains the 
offset and range of bytes to be locked (if any). 

ulTimeOut - input 
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The maximum time the call will wait, in milliseconds, for requested 
locks before returning to the application. Waiting/ time-out may occur 
when another application has placed locks on the same region. 
ulFlags - input 

The following flags may be specified: 


Bit Description 


Shared Q Request shared, read-only, access to the range. This 
allows other applications to obtain shared, read-only, 
access as well. Shared file ranges may not overlap ranges 
that are defined with exclusive access. If this bit is not 
set, then excusive access is requested and read/write 
access is obtained. No other application may obtain 
access to the range while locked. Exclusive lock ranges 
may not overlap other exclusive lock ranges. 


Atomic 1 Request atomic locking. The system will first unlock the 
file and then lock the file as an atomic operation. 
Atomic operations require the lock range and the 
unlock range to be the same, otherwise, an error is 
returned. Also, the application must have either shared 
access to the range, and is requesting exclusive access to 
it, or the application has exclusive access to the range, 
and is requesting shared access to it. If this bit is not set, 
atomic locking may or may not occur. 


31-2 These bits must be cleared. 


fhiLockld - input 


The file handle lock ID returned from a previous call to DosProtectOpen. 


RETURNS 


0 NO_ERROR 87 ERROR_INVALID_ 
PARAMETER 
6 ERROR_INVALID_HANDLE 95 ERROR_INTERRUPT 
33 ERROR_LOCK_VIOLATION 174 ERROR_ATOMIC_LOCK_ 
NOT_SUPPORTED 
36 ERROR_SHARING_ 175 ERROR_READ_LOCKS_ 
BUFFER _ EXCEEDED NOT_SUPPORTED 
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OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 428 DLL: DOSCALLS 

SEE ALSO 


DosCancelLockRequest -63-A, DosDupHandle -91, DosExecPgm -259, 
DosOpen -73 


NOTES 


The duration of a file lock should be short. 

If the lock and unlock ranges are both zero, then ERROR_ 
LOCK_VIOLATION is returned. 

When atomic locking is requested, the system will unlock the 
range first, and then lock the range. If an error occurs while attempt- 
ing to unlock the range, an error will be returned and the locking will 
not occur. If the unlock succeeds and the lock fails, an error is re- 
turned and the unlock remains in effect. 

DosClose will cause any existing file locks to be released in no spe- 
cific order. The same is true for an application that is terminating with 
an open file. 

File locks may be set beyond the range of the actual file. For ex- 
ample, a file that is 100 bytes in length may have locks defined for a 
range of 150 to 200, or for a range of -150 to -200. 

A request to lock the same file handle and the same range causes 
duplicate access to occur for the range. However, locked ranges are 
not inherited by child processes. 

Some file systems do not support atomic locking, such as the file 
systems included with OS/2 prior to version 2.00. 





DosSetFilePtr/DosProtectSetFilePtr File Management 


Sets the location of the file pointer. 


SYNTAX 


APIRET DosSetFilePtr (HFILE h/File, LONG (Distance, VLONG 
ulMovelype, PULONG pulAbsOffset) 
APIRET DosProtectSetFilePtr (HFILE hfFile, LONG (Distance, 
ULONG wulMoveType, PULONG 
pulAbsOffset, FHLOCK fhiLockld) 
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PARAMETERS 

hfFile - input 

A file handle. 

[Distance - input 

The signed distance to move, in bytes. 

ulMoveType - input 

The type of move to perform. Specify one of the following options: 


Constant Description 

FILE _ BEGIN Q (Distance indicates where to move relative to the 
beginning of the file. 

FILE CURRENT 1 (Distance indicates where to move relative to the 


current position of the file pointer. 


FILE END 2 (Distance indicates where to move relative to the 
end of a file. This can be used for determining a 
file’s size. 


pulAbsOffset - output 

This is the new of the file pointer relative to the beginning of the file. 
fhiLockld - input 

The file handle lock ID obtained from a previous call to DosProtect- 
Open. 


RETURNS 


0 NO_ERROR 130 ERROR_DIRECT_ 
ACCESS_HANDLE 

1 ERROR_INVALID_FUNCTION 131 ERROR _NEGATIVE_SEEK 

6 ERROR_INVALID_HANDLE 132 ERROR SEEK ON_DEVICE 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 256 DLL: DOSCALLS 

SEE ALSO 


DosOpen -73, DosRead -79, DosSetFileSize -86, DosWrite -90 


NOTES 


The lDistance parameter can be positive or negative; however, you can- 
not move to a negative position in a file. 
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This call does not work on character devices, pipes, or direct ac- 
cess handles. 





DosSetFileSize/DosProtectSetFileSize File Management 





Changes the size of an open file. 


SYNTAX 


APIRET DosSetFileSize (HFILE hffile, ULONG wlFileSize) 
APIRET DosProtectSetFileSize (HFILE h/fFile, ULONG ulFileSize, 
FHLOCK /hiLockld) 


PARAMETERS 

hfFile - input 

A file handle. 

ulFileSize - input 

The new size of the file, in bytes. 

fhiLockld - input 

The file handle lock ID obtained from a previous call to DosProtect- 
Open. 


RETURNS 
0 NO_ERROR 33 ERROR_LOCK_VIOLATION 
5 ERROR_ACCESS_DENIED 87 ERROR_INVALID_ 


PARAMETER 
6 ERROR_INVALID HANDLE 112 ERROR_DISK_FULL 
26 ERROR_NOT_DOS_DISK 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 21? DLL: DOSCALLS 

SEE ALSO 


DosOpen -73, DosQueryFileInfo -103, DosSetFileSize -86 


NOTES 


The file must be opened for write access for this call to succeed. 
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The size of the file may be increased or decreased (truncated). 

If the file size is being increased, the system will allocate the space 
on the medium immediately. The values of the new bytes are unde- 
fined. 


RESTRICTIONS/WARNINGS 

@ If the file size is being increased and there is not enough space on 
the disk to hold the new file’s size, then an error is returned, and the 
file size is set to zero (all data is lost). 





DosSetPathIinfo File Management 


Sets date, time, attribute, and extended attribute information on a file 
or directory. 


SYNTAX 

APIRET DosSetPathInfo(PSZ pszPath, ULONG ul/nfoLevel, PYOID 
plnfoBuf, ULONG ullnfoBufSize, VLONG 
ulPathInfoFlags) 


PARAMETERS 

pszPath - input 

The address of a buffer containing the null-terminated path of a file or 
directory. The path cannot contain wildcard characters. 

ullnfoLevel - input 

The level of information to set on the file. Specify one of the following: 


Constant Description 

FIL_ STANDARD 1 Date, time, or attribute information will be 
set. 

FIL_QUERYEASIZE 2 EAs will be set or cleared. 


The info level set will determine the format of the input buffer. 
plnfoBuf - input 
The address of a buffer containing the information to set. The format of this 
buffer is as follows: 
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Level 1 Information 

On input, a FILESTATUS3 structure containing the date, time, and at- 
tribute changes. For date and time fields, a value of zero causes no 
change to take place.. 


Level 2 Information 

On input, an EAOP2 structure. The f/pGEA2List field is ignored. The 
[prEA2List field must point to a buffer containing the list of FEA2s 
to set. FEA2 structures must be aligned on doubleword boundaries. 
The oNexiEntryOffset field must contain the number of bytes from 
the beginning of the current FEA2 to the start of the next FEA2. 
The oNextEntryOffset field of the last FEA2 must be set to zero. The 
EA value must begin after the FEA2 that is associated with it. The 
value must be in the format appropriate for its type. 

On output, nothing. The data on input is left unchanged unless there 
was an error, in which case, oErrorwill provide the offset to the FEA2 
that caused the problem. 


ullnfoBufSize - input 

The size, in bytes, of the buffer pointed to by plnfoBuf 

ulPathInfoFlags - input 

The only flag that may be specified is DSPI_WRTTHRU. This causes a 
synchronous write to occur for all the information that is set. This 
guarantees that EAs will get written before the call returns. 


RETURNS 
0 NO_ERROR 124 ERROR INVALID LEVEL 
32 ERROR SHARING _ 206 ERROR FILENAME _ 
VIOLATION EXCED_ RANGE 
87 ERROR INVALID _ 254 ERROR INVALID _ 
PARAMETER EA NAME 
122 ERROR INSUFFICIENT _ 255 ERROR EA LIST _ 
BUFFER INCONSISTENT 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 219 DLL: DOSCALLS 
SEE ALSO 


DosEnumAttribute -101, DosQueryFileInfo -103, 
DosQueryPathInfo -106, DosQuerySysInfo -109, DosSetFileInfo -80 
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NOTES 


For the call to succeed, the process must have exclusive write access to 
the file object. Therefore, any other process that has access to the file 
object will cause this call to fail. 

Specifying zero for any of the date and time components causes 
them to be left unchanged. 

When data integrity is essential, the DSPI_WRTTHRU bit should 
be used to ensure that EAs are written immediately to disk. However, 
excessive use of this option can cause performance problems. 

When FAs are modified, the last modification date and time are 
changed on the file object. 


RESTRICTIONS/WARNINGS 


@ If DosQueryPathInfo was used to obtain information on a directory 
so that it could be modified and set, be sure to remove the directory 
attribute that is returned in the FILESTATUS3 structure. The direc- 
tory attribute may not be specified for any reason, even if the file ob- 
ject is already a directory. 





DosSetVerify File Management 


Enables or disables write verification for the calling process. 


SYNTAX 
APIRET DosSetVerify (BOOL32 /32Venf\Flag) 


PARAMETERS 

f2VerifyFlag - input 

A value of 1 indicates that write verification should be turned on, and 
a value of 0 indicates that write verification should be turned off. 


RETURNS 

0 NO_ERROR 118 ERROR INVALID VERIFY_ 
SWITCH 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 


Ordinal: 210 DLL: DOSCALLS 
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SEE ALSO 
DosQueryVerify -112 


NOTES 


When write verification is on, the system verifies that the data written 
to disk is correctly recorded. Write verification should only be enabled 
for critical information since the performance of write operations will 
degrade noticeably. 





DosWrite/DosProtectWrite File Management 


Writes data to a file, pipe, or device. 


SYNTAX 


APIRET DosWrite (HFILE hfFile, PVOID pOutBuffer, VLONG 
ulOutBufLen, PULONG pulBytesWniten) 
APIRET DosProtectWrite (HFILE h/File, PVOID pOutBuffer, ULONG 
ulOutBufLen, PULONG pulBytesWniten, 
FHLOCK /fhiLockld) 


PARAMETERS 

hfFile - input 

The handle of the file, pipe, or device to write to. 
pOutBuffer - input 

A pointer to a buffer containing the data to write. 
ulOutBufLen - input 

The amount of data, in bytes, to write. 
pulBytesWritten - output 

The actual number of bytes written. 

fhiLockld - input 

The file handle lock ID obtained from a previous call to DosProtectOpen. 


RETURNS 


0 NO_ERROR 29 ERROR_WRITE_FAULT 

5 ERROR_ACCESS_ DENIED 33 ERROR_LOCK_VIOLATION 

6 ERROR_INVALID-HANDLE 109 ERROR_BROKEN_ PIPE 

19 ERROR_WRITE_PROTECT 157 ERROR_DISCARDED 

26 ERROR_NOT_DOS_DISK 233 ERROR_PIPE_NOT_ 
CONNECTED 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 282 DLL: DOSCALLS 
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SEE ALSO 
DosCreateNPipe -235, DosOpen -73, DosRead -79, DosSetFilePtr -84 


NOTES 


DosWrite will begin writing at the current file pointer position, and will 
adjust the file pointer after it finishes writing. 

The file must be opened for write access. 

If the file was opened with the write-through flag specified, then 
all data will be written to disk before the call returns; otherwise, the 
data will go through the cache. 

If the total number of bytes to write cannot fit on the disk, then no 
bytes are written, and wlBytesWritten is set to zero. 

A value of zero for ulOutBufLen is not an error, and is treated as a 
null operation by the system. 

If entire disk volume has been opened for direct access, you must 
first lock the volume before accessing it. 


File Handle Functions 





DosDupHandle duplicates or reassigns a file handle (pg. 91). 
DosQueryFHState/DosProtectQueryFHState gets the state of a file 
handle (pg. 93). 

DosQueryHType gets the type of file handle—either network or local 
file, pipe, or device (pg. 95). 

DosResetBuffer flushes the buffers associated with a given file handle 
(pg. 153). 

DosSetFHState/DosProtectSetFHState sets the open mode options of 
a file handle (pg. 97). 

DosSetMaxFH sets the maximum number of file handles for the 
process (pg. 98). 

DosSetRelMaxFH sets the relative number of file handles for the 
process (pg. 99). 





@ DosDupHandle File Management 


Creates a duplicate file handle for an open file or pipe. 
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SYNTAX 
APIRET DosDupHandle(HFILE hfHandle, PHFILE phfNewHandle) 


PARAMETERS 

hfHandle - input 

The file handle to be duplicated. 

phfNewHandle - input/output 

On input, the address of an HFILE that contains the method of dupli- 
cation: 


Value Description 
OxFFFFFFF Allocate a new file handle. 
not OXFFFFFFFF Close the old handle and assign this value as the 


new file handle. This value can be any currently 
valid file handle accessible to the process including 
any of the standard I/O handles. The standard I/O 
handles are: 0 Standard In, 1 Standard Out, 

2 Standard Error. 


On output, if OxFFFFFFFF was specified, then phfNewHandle will con- 
tain the new handle allocated by the system. 


RETURNS 

0 NO_ERROR 6 ERROR INVALID HANDLE 

4 ERROR TOO MANY. 114 ERROR INVALID _ 
OPEN_FILES TARGET HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 260 DLL: DOSCALLS 

SEE ALSO 


DosClose -64, DosCreatePipe -230, DosDupHandle -91, DosOpen -73, 
DosRead -79, DosSetMaxFH -98, DosSetRelMaxFH -99, DosWrite -90 


NOTES 


Duplicating a pipe handle causes a link to be created between handle- 
specific information. Therefore, if the read pointer for one handle 
moves, it will also move for the duplicated file handle and vice versa. 
However, if hfHandle is closed, it will not affect the duplicate handle. 
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When the child process terminates, the phfNewHandlewill be closed au- 
tomatically. 

If a handle of a currently open pipe is specified for phfNewHandke, 
it is closed before being redefined as the duplicate handle. 


RESTRICTIONS/WARNINGS 


@ Care should be taken when assigning new handles, since arbitrarily 
assigning a handle that is being used for other purposes could cause 
some interesting problems that are difficult to debug. 





DosQueryFHState/DosProtectQuery— File Management 
FHState 


Obtains the state of the file handle. 


SYNTAX 


APIRET DosQueryFHState (HFILE h/fFile, PULONG pulState) 
APIRET DosProtectQueryFHState (HFILE hfFile, PULONG pulsSiate, 
FHLOCK /hl/d) 


PARAMETERS 

hfFile - input 

The file handle to query. 

pulState - input 

The address of a ULONG that will receive the state information. The 
defaults are in italics. 


Constant Description 


Open modes: 


OPEN_FLAGS_DASD 0x8000 The handle actually references a 
mounted volume (such as A:, C:) that 
has been opened for direct access. 


OPEN_FLAGS WRITE = _0x4000__—‘ File accesses are handled 

THROUGH synchronously. The file writes may go 
through the system’s cache; however, 
the data will actually be written to disk 
before the call returns. This attribute is 
not inherited by child processes. 
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OPEN_FLAGS FAIL _ 0x2000 Media I/O errors will not be 

ON_ERROR reported via the system-critical error 
handler, but reported to the caller via 
return code. This attribute is not 
inherited by child processes. Note: 
Media I/O errors that are generated as 
a result of a Category 8 IOCTL 
function are always reported via return 


code. 
OPEN_FLAGS NO_ 0x1000 File I/O operations should not be 
CACHE routed through the file system driver’s 


cache. This attribute is not inherited by 
child processes. 


OPEN_FLAGS _ 0x0080 The file handle will not be inherited by 
NOINHERIT child processes. This attribute is not 
inherited by child processes. 


Sharing modes: 


Specifies the types of accesses other processes should not have while the file 
is open. Sharing modes remain in effect until the process is closed or until 
the process terminates. 


OPEN_SHARE _ 0x0010 No other process may open the file. 
DENYREADWRITE 

OPEN_SHARE_ 0x0020 No other process may open the file for 
DENYWRITE writing. 

OPEN_SHARE _ 0x0030 No other process may open the file for 
DENYREAD reading. 

OPEN_SHARE _ 0x0040 Deny neither read nor write access. 
DENYNONE 


Sharing modes are inherited by child processes inheriting the file handle. 


Access modes: 


Indicates accesses requested by the process. If another process has the file 
open and has restricted sharing privileges, then an access-denied error may 
be returned by the system. 
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OPEN_ACCESS_READONLY 0x0000 The file has been opened for 
reading only. 


OPEN_ACCESS_WRITEONLY  0x0001 The file has been opened for 
write-only. 


OPEN_ACCESS_READWRITE  0x0002 The file has been opened for 
reading and writing. 


Access modes are inherited by child processes inheriting the file handle. 


fhild - input 
The file handle lock ID that was returned from a call to DosProtect- 





RETURNS 

0 NO_ERROR 6 ERROR INVALID HANDLE 
OTHER INFO 

Include file: bsedos.h Define: INCL _DOSFILEMGR 

Ordinal: 276 DLL: DOSCALLS 

SEE ALSO 

DosDevIOCtl -4, DosOpen -73, DosSetFHState -97 

NOTES 

None 

DosQueryH Type File Management 


Determines the locality and type of device the handle refers to. 


SYNTAX 

APIRET DosQueryH Type (HFILE /hFile, PULONG pulHandleType, 
PULONG pulFlagWord) 

PARAMETERS 


fhfile - input 
The file handle to query. 
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pulHandleType - output 
The address of a ULONG that will receive the handle type information 
as described below: 


Bit Description 
15 Network bit 
0: The handle is for a local file, device, or pipe. 


1: The handle is for a remote file, device, or pipe. 


14 1: The handle is a protected file handle. 
13-8 Reserved. 
7-0 (Treat as a byte) The low byte describes the handle class as follows: 
Value Description 
0 Disk file 
] Character device 
a Pipe 


Values greater than 2 are reserved. 


pulFlagWord - output 
The address of a ULONG that will receive the device driver attribute 
word if the handle refers to a local character device. 


RETURNS 

0 NO_ERROR 6 ERROR INVALID HANDLE 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 224 DLL: DOSCALLS 

SEE ALSO 


DosOpen -73, DosQueryFHState -93 


NOTES 


None 
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DosSetFHState/DosProtectSetFHState File Management 





Sets the file handle modes on the specified file handle. 


SYNTAX 


APIRET DosSetFHState (HFILE hAffile, ULONG ulFileHandleMode) 
APIRET DosProtectSetFHState (HFILE h/fFile, ULONG ulFileHandle- 
Mode, FHLOCK /hLockId) 


PARAMETERS 

hfFile - input 

The file handle whose modes are to be changed. 
ulFileHandleMode - input 

Only the following file handle modes may be specified: 


Constant Hex/Bit Description 


Open modes: 


OPEN_ FLAGS _ 0x4000/14 File accesses are handled 

WRITE_THROUGH synchronously. The file writes may go 
through the system’s cache; however, 
the data will actually be written to disk 
before the call returns. This attribute is 
not inherited by child processes. 


OPEN_FLAGS _ 0x2000/13 Media I/O errors will not be reported 

FAIL_ON_ERROR via the system-critical error handler, but 
to the caller via return code. This 
attribute is not inherited by child 
processes. Note: Media I/O errors that 
are generated as a result of a Category 
8 IOCTL function are always reported 
via return code. 


OPEN_ FLAGS _ 0x1000/12 File I/O operations should not be 

NO_CACHE routed through the file system driver’s 
cache. This attribute is not inherited by 
child processes. 


OPEN_FLAGS _ 0x0080/7 The file handle will not be inherited by 
NOINHERIT child processes. This attribute is not 
inherited by child processes. 
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Note: Bits 3 and 8-11 must be set to the values returned from a call 
to DosQueryFHState. All other bits must be set to 0. 
fhiLockld - input 
The file handle lock ID returned from a previous call to DosProtect- 
Open. 


RETURNS 


0 NO_ERROR 6 ERROR_INVALID HANDLE 
87 ERROR_INVALID_PARAMETER 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: Zot DLL: DOSCALLS 


SEE ALSO 


DosClose -64, DosDevIOCtl -4, DosDupHandle -91, DosExecPgm -259, 
DosOpen -73, DosQueryFHState -93 


NOTES 


Since the system does not guarantee the write order of multisector 
writes, applications requiring a specific write order must individually 
write each sector. Changing the write-through flag has no effect on write 
operations that have already placed data in the system buffer cache. 

File handle modes can be queried by calling DosQueryFHState. 

Only the inheritance bit and the write-through bit can be changed 
for named pipes. When the write-through bit is on, it prevents write- 
behind operations on named pipes. 





DosSetMaxFH File Management 


Sets the maximum number of file handles for the calling process. 


SYNTAX 
APIRET DosSetMaxFH(ULONG ulNumHandles) 


PARAMETERS 


ulNumHandles - input 
The total number of allocatable file handles. 
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RETURNS 

0 NO_ERROR 87 ERROR INVALID _ 
PARAMETER 

8 ERROR NOT_ENOUGH_MEMORY 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 209 DLL: DOSCALLS 

SEE ALSO 


DosDupHandle -91, DosOpen -73, DosSetReIMaxFH -99 


NOTES 


You can only use DosSetMaxFH to increase the number of file handles. 
An attempt to decrease them will cause an ERROR_INVALID_PARA- 
METER to be returned. 

The maximum number of file handles is 32768. An attempt to al- 
locate more than 32768 handles will result in an ERROR INVALID _ 
PARAMETER return code. 

The new number of file handles will be inherited by any subse- 
quently started child processes. 





DosSetRelMaxFH File Management 





Adjusts the current number of file handles upward by the specified 
amount. 


SYNTAX 
APIRET DosSetRelMaxFH (PLONG plAmount, PULONG pulMaxFH) 


PARAMETERS 

plAmount - input 

The address of a LONG that contains the number of file handles by 
which to increase the current maximum file handles for the calling 
process. If the amount is a negative number, then the maximum num- 
ber of file handles is decreased. This is more of a request than a com- 
mand, since the system may choose to disregard the request. 
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pulMaxFH - output 
The address of a ULONG that contains the new total number of allo- 
cated file handles. 


RETURNS 
0 NO_ERROR 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 382 DLL: DOSCALLS 


SEE ALSO 
DosDupHandle -91, DosOpen -73, DosSetMaxFH -98 


NOTES 


This call does not affect any currently open file handles. It will return 
a good return code even if the request was disregarded. 

Passing a value of zero for [Amount can be used to determine the 
current maximum number of file handles for the calling process. 

The maximum number of file handles is 32768. 

The new number of file handles will be inherited by any subse- 
quently started child processes. 


File Query Functions 





DosEnumAttribute /DosProtectEnumAttribute enumerates the ex- 
tended attribute names and sizes of a file or directory (pg. 101). 
DosQueryFileInfo/DosProtectQueryFileInfo returns information 
about an open file (pg. 103). 

DosQueryPathInfo returns information about a file or subdirectory 
(pg. 106). 

DosQuerySysInfo returns the values of static system variables (pg. 109). 
DosQueryVerify determines the write verification state of a process 


(pg. 112). 
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DosEnumAttribute/DosProtectEnum File Management 
Attribute 





Enumerates extended attribute names and lengths for a file or direc- 
tory. 


SYNTAX 


APIRET DosEnumAttribute(ULONG wlRefType, PVOID pFileRey, 
ULONG ulEnitryNum, PVOID pEnumBuf, 
ULONG uwlEnumBufSize, PULONG 
pulEnumCount, ULONG ullnfoLevel) 
APIRET DosProtectEnumAttribute (ULONG wlRefType, PYVOID 
pFileRef, ULONG ulEniryNum, 
PVOID pEnumBuf, VLONG 
ulEnumBufSize, PULONG 
pulEnumCount, ULONG 
ullnfoLevel, FHLOCK /fhild) 


PARAMETERS 


ulRefType - input 
Specify whether pFileRef points to a file handle or null-terminated 
string as follows: 


Constant Description 
ENUMEA_REFTYPE_FHANDLE 0 File handle. 
ENUMEA_REFTYPE PATH 1 Null-terminated name of a file 


or directory. 


pFileRef - input 

The address of a file handle or the address of a null-terminated string 
containing the name of the file or directory. 

ulEntryNum - input 

The ordinal of the entry where enumeration is to begin. A value of | 
indicates the first EA; a value of 2 is the second EA, and so on. A value 
of 0 is reserved. 

pEnumBuf - output 

The address of a buffer that will receive the enumerated EA informa- 
tion. Level 1 information is returned in a series of DENA2 data struc- 
tures. 
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ulEnumBufSize - input 

The size, in bytes, of the buffer pointed to by pEnumBuf: 
pulEnumCount - input/output 

On input, the address of a ULONG containing the number of EAs to 
enumerate. A value of -1 indicates that all EAs, up to what will fit in 
pEnumBuf, will be returned. On output, the address of a ULONG con- 
taining the actual number of EAs returned. The EAs are returned in 
the form of doubleword-aligned DENA2 structures. 

ullnfoLevel - input 

The level of information requested. Currently, only a value of 1 (ENU- 
MEA_LEVEL_NO_VALUE) may be specified for this parameter. 

fhild - input 

The file handle lock ID that was returned from a call to DosProtect- 
Open. 


RETURNS 

0 NO_ERROR 87 ERROR_INVALID_ 
PARAMETER 

3 ERROR _PATH_NOT_FOUND 111 ERROR _BUFFER_ 
OVERFLOW 


5 ERROR_ACCESS_ DENIED 124 ERROR_INVALID_LEVEL 
6 ERROR _INVALID-HANDLE 206 ERROR_FILENAME_ 
EXCED_RANGE 


8 ERROR NOT_ENOUGH_ 253 ERROR INVALID PATH 
MEMORY 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 3/2 DLL: DOSCALLS 

SEE ALSO 


DosCreateDir -121, DosOpen -73, DosQueryFileInfo -103, 
DosQueryPathInfo -106, DosSetFileInfo -80, DosSetPathInfo -87 


NOTES 


This call will not return the values of EAs—merely the names and sizes 
of the EAs. 

This function is typically used to determine the amount of buffer 
space needed to hold the full FEA2 structure that is returned from a 
call to DosQueryFileInfo and DosQueryPathInfo. 
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DosEnumAttribute does not lock the file being enumerated dur- 
ing its processing. Therefore, if an application needs to ensure that the 
FAs will not be modified while the enumeration is being performed, it 
should first open the file with with the sharing mode set to deny-write. 
This step is not necessary for directories, since sharing is not possible. 





DosQueryFilelnfo/DosProtectQuery-— File Management 
FileInfo 





Returns information about an open file. 


SYNTAX 


APIRET DosQueryFileInfo (HFILE h/fFile, ULONG wllnfoLevel, PVOID 
plnfoBuf, VLONG ullnfoBufSize) 
APIRET DosProtectQueryFileInfo (HFILE h/File, ULONG wullnfoLevel, 
PVOID plnfoBuf, ULONG ullnfo- 
BufSize, FHLOCK /hild) 


PARAMETERS 

hfFile - input 

The file handle to query. 
ullnfoLevel - input 

The query type to perform: 


Constant Description 


FIL_ STANDARD 1 Return level 1 file information. This is 
standard file information. 


FIL_QUERYEASIZE 2 Return level 2 file information. This 
includes information returned from a 
level 1 search, plus the size of the 
specified EAs. 


FIL_QUERYEASFROMLIST 3 Returns the values of the requested EAs. 


The type of query performed will determine the format of the 
buffer returned. 
plnfoBuf - input/output 
The address of a buffer that will receive the data structures returned by 
level 1 through level 3 queries. The type of structure returned is de- 
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pendent on the type of query. This buffer is also used for input for a 
level 3 search to specify the EA information to return. The buffer is 
used as follows: 


Level 1 Information 

On input, nothing. On output, the buffer contains a FILEFINDBUF3 
structure. The file name returned in the FILEFINDBUF3 structure 
is not fully qualified. 


Level 2 Information 

On input, nothing. On output, the buffer contains a FILEFINDBUF4 
structure. The FILEFINDBUF4 structure contains all the informa- 
tion found in a FILEFINDBUFS3 structure, plus the size of the EAs 
attached to the object. The EA size information may be used to cal- 
culate the buffer size necessary to hold the EAs returned from a 
level 3 query. 


Level 3 Information 

On input, specify an EAOP2 structure. The /pGEA2List field of the 
EAOP2 structure is a pointer to a GEA2LIST which defines the at- 
tribute names whose EA values are to be returned. Each GEA2 in 
the list must be aligned on 4byte boundaries. The oNextEntryOffset 
field must specify the number of bytes from the beginning of the 
current GEA? to the beginning of the next GEA2. Set oNextEntry- 
Offset to zero to indicate there are no more entries. The cbList field of 
GEA2List should specify the total size of the buffer pointed to by 
[pGEAZList. The space needed to hold /fpFEA2List must be allocated 
by the application. Additionally, the cbList field of fpFEA2List must 
contain the size, in bytes, of the space reserved to hold the returned 
EFAs. On output, the buffer pointed to by /pFEA2List will contain the 
values of the EAs requested. 


The FEA2s returned may be in a different order than as specified 
on input in the fpGEA2List; therefore, the names of the EAs must be 
checked so they are correctly matched to the EA values that are re- 
turned. 

If a particular object does not have one of the EAs requested, then 
that EA’s cbValue field in the FEA2 structure will be set to zero. 

If the buffer is too small to hold the returned EAs, then ER- 
ROR BUFFER OVERFLOW is returned, and the cbLust field of the 
FEA2LIST structure contains the size of the entire EA set for the file 
even if only a portion of the EAs were returned (assuming there is at 
least enough room to hold the cbList field in the buffer). 


File Management 105 


The cbList field of the FEA2LIST structure will include the bytes 
that were required (if any) to doubleword-align the returned FEA2 
structures. 

The size of the buffer required to hold the EA set will be less than 
or equal to twice the EA set that is stored for the object on disk. It isa 
good idea to first perform a level 2 query or to call DosEnumAttribute 
to determine the size of the EAs found in the file, and then perform 
the level 3 query with the correctly calculated buffer size. ‘The buffer 
size can be calculated following a level 2 search by using the following 
formula: 


Sizeof (EAOP2) + sizeof(FILEFINDBUF3) + fea2list.cbList + (NumEAs * 3) 


The last part of the calculation is to account for pad bytes that may be 
necessary to doubleword-align the FEA2 structures. 

ullnfoBufLen - input 

The size, in bytes, of the buffer pointed to by plnfoBuf. 

fhiLockld - input 

The file handle lock ID returned from a previous call to DosProtect- 
Open. 


RETURNS 
0 NO_ERROR 124 ERROR INVALID LEVEL 
5 ERROR ACCESS _ 130 ERROR_DIRECT_ 
DENIED ACCESS HANDLE 
6 ERROR INVALID _ 254 ERROR INVALID _ 
HANDLE EA NAME 
111 ERROR BUFFER_ 255 ERROR EA LIST_ 
OVERFLOW INCONSISTENT 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 279 DLL: DOSCALLS 
SEE ALSO 


DosEnumAttribute -101, DosOpen -73, DosQueryPathInfo -106, 
DosResetBuffer -96-A, DosSetFileInfo -80, DosSetPathInfo -87 


NOTES 


On FAT file systems, the creation and access dates and times are set to 
zero for level 1 queries. 
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DosQueryFileInfo must have read access to the file being queried, 
and the file must have been opened with deny-write sharing mode 
specified. 





DosQueryPathInfo File Management 


Returns information about a file or directory via a fully qualified path. 


SYNTAX 


APIRET DosQueryPathInfo(PSZ pszPathName, ULONG ullnfoLevel, 
PVOID plnfoBuf, VLONG ullnfoBufSize) 


PARAMETERS 


pszPathName- input 

A null-terminated buffer containing the file or directory to query. 
Metacharacters (wildcards) may only be used in level 5 queries. 
ulInfoLevel - input 

The query type to perform: 


Constant Description 


FIL_STANDARD 1 Return level 1 file information. This is 
standard file information. 


FIL_QUERYEASIZE 2 Return level 2 file information. This 
includes information returned from a 
level 1 search, plus the size of the 
specified EAs. 


FIL_QUERYEASFROMLIST 3 Returns the values of the requested EAs. 


FIL_QUERYFULLNAME 5 Returns the fully qualified name of the 
file or directory specified in pszPathName. 


The type of query performed will determine the format of the 
buffer returned. 
pInfoBuf - input/output 
The address of a buffer that will receive the data structures returned by 
level 1 through level 3 queries. The type of structure returned is de- 
pendent on the type of query. This buffer is also used for input for a 
level 3 search to specify the EA information to return. The buffer is 
used as follows: 
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Level 1 Information 

On input, nothing. On output, the buffer contains a FILEFINDBUF3 
structure. The file name returned in the FILEFINDBUF3 structure 
is not fully qualified. 


Level 2 Information 

On input, nothing. On output, the buffer contains a FILEFINDBUF4 
structures. The FILEFINDBUF4 structure contains all the informa- 
tion found in a FILEFINDBUFS3 structure, plus the size of the EAs at- 
tached to the object. The EA size information may be used to calcu- 
late the buffer size necessary to hold the EAs returned from a level 
3 query. 


Level 3 Information 

On input, specify an EAOP2 structure. The /pGEA2List field of the 
EAOP2 structure is a pointer to a GEA2LIST which defines the at- 
tribute names whose EA values are to be returned. Each GEA2 in 
the list must be aligned on 4byte boundaries. The oNextEntryOffset 
field must specify the number of bytes from the beginning of the 
current GEA2 to the beginning of the next GEA2. Set oNexiEntry- 
Offset to zero to indicate there are no more entries. The cbList field 
of GEA2List should specify the total size of the buffer pointed to by 
/pGEA2List. The space needed to hold the /fpFEA2List must be allo- 
cated by the application. Additionally, the cbList field of fpFEA2List 
must contain the size, in bytes, of the space reserved to hold the re- 
turned EAs. 


On output, the buffer pointed to by /pFEA2List will contain the val- 
ues of the EAs requested. 

The FEA2s returned may be in a different order than as specified 
on input in the /pGEA2List, therefore, the names of the EAs must be 
checked so they are correctly matched to the EA values that are re- 
turned. 

If a particular object does not have one of the EAs requested, then 
that EA’s cbValue field in the FEA2 structure will be set to zero. 

If the buffer is too small to hold the returned EAs, then ER- 
ROR BUFFER OVERFLOW is returned, and the cbList field of the 
FEA2LIST structure contains the size of the entire EA set for the file 
even if only a portion of the EAs were returned (assuming there is at 
least enough room to hold the cbList field in the buffer). 

The cbList field of the FEA2LIST structure will include the bytes 
that were required (if any) to doubleword-align the returned FEA2 
structures. 
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The size of the buffer required to hold the EA set will be less than 
or equal to twice the EA set that is stored for the object on disk. It is a 
good idea to first perform a level 2 query or to call DosEnumAttribute 
to determine the size of the EAs found in the file, and then perform 
the level 3 query with the correctly calculated buffer size. The buffer 
size can be calculated following a level 2 search by using the following 
formula: 


sizeof (EAOP2) + sizeof (FILEFINDBUF3) + fea2list.cbList + (NumEAs * 3) 


The last part of the calculation is to account for pad bytes that may 
be necessary to doubleword-align the FEA2 structures. 


Level 5 Information 

On input, nothing. On output, the fully qualified path of the file or di- 
rectory pointed to by pszPathName. If no path or drive is specified in 
pszPathName, the function will simply prefix the value pointed to by 
pszPathName with the current drive and directory. If a path with no 
drive is specified in pszPathName then the drive will be prefixed to it. 
The call makes no attempt to verify that the file or directory actually 
exists. 


ullnfoBufLen - input 
The size, in bytes, of the buffer pointed to by plnfoBuf. 


RETURNS 
0 NO_ERROR 124 ERROR INVALID LEVEL 
2 ERROR FILE NOT_ 130 ERROR DIRECT _ 
FOUND ACCESS HANDLE 
3 ERROR PATH NOT_ 206 ERROR FILENAME _ 
FOUND EXCED_ RANGE 
5 ERROR ACCESS DENIED 253 ERROR INVALID PATH 
32 ERROR SHARING _ 254 ERROR INVALID _ 
VIOLATION EA NAME 
111 ERROR BUFFER _ 255 ERROR EA LIST _ 
OVERFLOW INCONSISTENT 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSFILEMGR 


Ordinal: 220 DLL: DOSCALLS 
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SEE ALSO 


DosEnumAttribute -101, DosQueryFileInfo -103, DosOpen -73, 
DosResetBuffer -96-A, DosSetFileInfo -80, DosSetPathInfo -87 


NOTES 


On FAT file systems, the creation and access dates and times are set to 
zero for level | queries. 

DosQueryPathInfo must be able to obtain read access to the file or 
directory being queried. 





DosQuerySysinfo File Management 


Obtains the values of system variables. 


SYNTAX 


APIRET DosQuerySysInfo (ULONG uwlStartOrdinal, ULONG 
ulEndOrdinal, PVOID pBuffer, ULONG 
ulBufLen) 


PARAMETERS 


ulStartOrdinal - input 

The ordinal of the first variable to return. One of the values in the fol- 
lowing Notes section may be specified. 

ulEndOrdinal - input 

The ordinal of the last variable to return. This value must be greater 
than or equal to wlStartOrdinal. See ulStartOrdinal for a list of valid or- 
dinals. 

pBuffer - output 

The address of a buffer that will receive the requested system variables. 
Variables will be written to the buffer in descending order. Each vari- 
able requires a doubleword of space. 

ulBufLen - input 

The size, in bytes, of the buffer pointed to by pBuffer. 


RETURNS 


QO NO_ERROR 111 ERROR _BUFFER_ OVERFLOW 
87 ERROR_INVALID_PARAMETER 
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OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 348 DLL: DOSCALLS 

SEE ALSO 


DosQueryCurrentDir -124, DosQueryCurrentDisk -125, 
DosQueryFileInfo -103, DosQueryFSInfo -152, 
DosQueryPathInfo -106, DosQueryVerify -112 


NOTES 


Constant Description 


QOSV_MAX_PATH_ LENGTH 1 The maximum system-supported path 
length. The path length includes the 
drive specifier (c:), the leading backslash 
(\), and the null terminator. 


QOSV_MAX_TEXT_SESSIONS 2 The maximum number of simultaneous 
full-screen/windowed text sessions. 


OSV_MAX_PM_SESSIONS 3 The maximum number of simultaneous 
PM sessions. 


OSV_MAX_VDM_SESSIONS 4 The maximum number of simultaneous 
VDM sessions. 


OSV_BOOT_DRIVE 5 ‘The drive the system booted from (A = I, 
B = 2, and so on). 


QSV_DYN_PRI_VARIATION _ 6 Indicates whether dynamic priority 
scheduling is on; 1 = TRUE, 0 = FALSE. 


OSV_MAX_WAIT 7 The maximum time in seconds that a 
thread must wait before receiving a 
priority boost. 

QSV_MIN_SLICE 8 The minimum time slice in seconds. 

OSV_MAX_SLICE 9 The maximum time slice in seconds. 

OSV_PAGE_SIZE 10 The size of amemory page in bytes. On 


Intel architecture, this value is 4096. 


QSV_VERSION_MAJOR 11 The major version of the operating 
system. 


OSV_VERSION_MINOR 


QSV_MS_COUNT 


QSV_TIME_LOW 


QSV_TIME_HIGH 


QSV_TOTPHYSMEM 


QSV_TOTRESMEM 


OSV_TOTAVAILMEM 


OSV_MAXPRMEM 


OSV_MAXSHMEM 


QSV_TIMER_ INTERVAL 


14 


15 


16 


17 


18 


19 


20 


21 


22 


OSV_MAX_ COMP_LENGTH 23 
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The minor version of the operating 
system. 


The value of a 32-millisecond counter 
that is set to zero when the system is 
started. 


The 32-bit, low-order value of the time in 
seconds since January 1, 1970 at 
00:00:00. 


The 32-bit, high-order value of the time 
in seconds since January 1, 1970 at 
00:00:00. 


The total number of bytes of physical 
memory in the system. 


The total number of bytes of physical 
memory that are locked by device drivers 
(and not swappable). 


The total number of bytes of memory 
that are currently available to all 
processes on the system. This value is 
only intended to provide a general idea 
of available memory; it is not guaranteed 
to be accurate. 


The number of bytes that can be 
allocated by the calling process in its 
private arena. This value is only intended 
to provide a rough idea and is not 
guaranteed. 


The number of bytes that can be 
allocated in the shared arena. This value 
is only intended to provide a rough idea 
and is not guaranteed. 


The timer interval in tenths of a 
millisecond. This is based on the system’s 
clock chip. 


The maximum length of any given 
component of a path name. 
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QOSV_FOREGROUND_FS_ 24 The current fullscreen foreground 





SESSION session ID. 
OSV_FOREGROUND _ 25 The process ID of the current 
PROCESS foreground process. 
QSV_NUMPROCESSORS 26 The number of processors in the 
machine. 
@ DosQueryVerify File Management 


Determines whether the calling process has write verification enabled. 


SYNTAX 
APIRET DosQueryVerify(PBOOL32 pfVerify Mode) 


PARAMETERS 

pfVerifyMode - output 

The address of a BOOL32 that will receive the write verification mode. 
A return of 0 indicates write verification is not active; 1 indicates write 
verification is active. 


RETURNS 
0 NO_ERROR 


OTHER INFO 


Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 225 DLL: DOSCALLS 


SEE ALSO 
DosSetVerify -89 


NOTES 


When write verification is active, the system ensures that the data is cor- 
rectly written to disk. Errors occurring from nonverified writes are 
rare. 
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Directory Search Functions 





DosFindClose ends a search for a given directory handle (pg. 113). 
DosFindFirst begins a search for files for a given directory (pg. 113). 
DosFindNext continues a search started with DosFindFirst (pg. 119). 





@ DosFindClose File Management 





Closes the handle of a find request, thereby terminating the search. 


SYNTAX 
APIRET DosFindClose (HDIR hdirSearch) 


PARAMETERS 


hdirSearch - input 
The handle of the search request to be terminated. This handle is re- 
turned from by DosFindFirst. 





RETURNS 
0 NO_ERROR 6 ERROR INVALID HANDLE 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 263 DLL: DOSCALLS 
SEE ALSO 
DosFindFirst -113, DosFindNext -119 
NOTES 
None 
@ DosFindFirst File Management 


Begins a search for files or directories via name and attribute matching. 
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SYNTAX 


APIRET DosFindFirst (PSZ pszFileOrDir, PHDIR phdirSearch, ULONG 
ulFileAtiributes, PVOID pResuliBuf, VLONG 
ulResultBufLen, PULONG pulSearchCount, 
ULONG uwllnfoLevel) 


PARAMETERS 

pszFileOrDir - input 

A null-terminated string containing the name of the file or directory to 
be found. Metacharacters (wildcards) may be specified in the name 
component. 

phdirSearch - input/output 

On input, specify one of the following: 


Constant Description 


HDIR_SYSTEM 0x00000001 The system will assign the handle of 
standard output, which is always 
available to a process. 


HDIR_CREATE OxFFFFFFFF The system will allocate and return a 
unique search handle in phdirSearch. 


The handle returned by DosFindFirst must be specified on subse- 
quent DosFindNext calls. Reusing a handle on a subsequent DosFind- 
First call causes the original search to be terminated, and a new search 
to be started. 
ulFileAtiributes - input 
Specify a combination of the following attributes to narrow the search: 


Attribute Description 


MUST_HAVE_ARCHIVED —_0x00002000 The object must have the 
archive attribute to match the 
search criteria. 


MUST_HAVE_DIRECTORY 0X00001000 The object must have the 
directory attribute to match the 
search criteria. 


MUST_HAVE_SYSTEM 0x00000400 The object must have the system 
attribute to match the search 
criteria. 
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MUST_HAVE_HIDDEN 0x00000200 The object must have the 
hidden attribute to match the 
search criteria. 


MUST_HAVE_READONLY  0x00000100 The object must have the read- 
only attribute to match the 
search criteria. 


FILE_ARCHIVED 0x00000020 The object may have the archive 
attribute set. 


FILE_DIRECTORY 0x00000010 The object may have the 
directory attribute set. 


FILE_SYSTEM 0x00000004 ‘The object may have the system 
attribute set. 


FILE_HIDDEN 0x00000002 The object may have the hidden 
attribute set. 


FILE_READONLY 0x00000001 The object may have the 
readonly attribute set. 


All searches are inclusive of any normal files (that is, files with no 
attributes) and read-only files matching the file mask, in addition to 
the files that match the specified attributes. 

The must-have attributes are used to narrow the search by requir- 
ing the found objects to have the must-have attributes to be considered 
a match. When any must-have flags are specified, the corresponding 
may-have attributes must be specified for a match to occur. For exam- 
ple, to find files that must have the archive attribute, but can have any 
other attribute as well except the directory attribute, the following 
must be specified: 


MUST_HAVE_ARCHIVED | FILE_ARCHIVED | FILE_HIDDEN | FILE_SYSTEM | 
FILE READONLY 


An application may exclude objects that have specific attributes by 
specifying the desired must-have attribute without specifying the cor- 
responding may-have attribute. 
pResultBuf - input/output 
The address of a buffer that will receive the data structures returned by 
level 1 through level 3 searches. The type of structure returned is de- 
pendent on the type of search. This buffer is also used for input for a 
level 3 search to specify EA information. The buffer is used as follows: 
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Level 1 Information 

On input, nothing. On output, the buffer contains 1 or more FILE- 
FINDBUFS3 structures. The number of structures returned will de- 
pend on the value specified for pulSearchCount and the number of 
objects that were found. The FILEFINDBUFS structure has a fixed 
length. The file name returned in the FILEFINDBUF3 structure is 
not fully qualified. 


Level 2 Information 

On input, nothing. On output, the buffer contains 1 or more FILE- 
FINDBUF4 structures. The number of structures returned will de- 
pend on the value specified for pulSearchCount and the number of 
objects that were found. The FILEFINDBUF4 structure has a fixed 
length and contains all the information found in level I informa- 
tion, plus the size of the EAs of the object. 


Level 3 Information 

On input, specify an EAOP2 structure. The fpGEA2List field of the 
EAOP2 structure is a pointer to a GEA2LIST which defines the at- 
tribute names whose EA values are to be returned. The request for 
the EA values does not add an additional match constraint to the 
search, and is merely a request for the EA values of the files/direc- 
tories that meet the name and attribute requirements. 


On output, the buffer has the following sequence in memory: 


Structure Notes 


EAOP2 This structure is left untouched by the system upon 
return with the exception of the oError field (if 
applicable). The system does not set the fpFEA2List field. 


FILEFINDBUF3 = Only the structure members up to the cchName field are 
returned. Then the FEA2LIST begins. 


FEA2LIST This structure begins (or “preempts”) starting with the 
cchName field of the FILEFINDBUF3 structure above. 
FEA2 Each FEA2 structure will begin on a 
doubleworld boundary. These two 
field 
fEA (2 bytes) The EA flags. This indicates the type of eo 


repeated for 
each EA 
returned. 


EA returned. This field follows 
immediately after the null-terminated EA 
name returned in the FEA2 structure. 
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EA data The EA data that is appro- 


This field is repeated 
practi Cie peaeS for each EA returned. 
(check fEA). 
3 bytes of Skip 3 bytes. 
undefined data These three fields 
Length of file The length of the file name minus | “© FOHING ASK Aner 
name (CHAR) the null. the last EA 
returned. 
File name The null-terminated, nonqualified 
(CHAR [ ]) file name. 


The FEA2s returned may be in a different order than as specified 
on input in the fpGEA2List, therefore, the names of the EAs must be 
checked so they are correctly matched to the EA values that are re- 
turned. 

If a particular object does not have one of the EAs requested, then 
that EA’s cbValue field in the FEA2 structure will be set to zero. 

If the buffer is too small to hold the returned EAs, then ER- 
ROR_BUFFER_ OVERFLOW is returned, and the cbList field of the 
FEA2LIST structure contains the size of the entire EA set for the file 
even if only a portion of the EAs were returned (assuming there is at 
least enough room to hold the cbList field in the buffer). 

The cbList field of the FEA2LIST structure will include the bytes 
that were required (if any) to doubleword-align the returned FEA2 
structures. 

The size of the buffer required to hold the EA set will be less than 
or equal to twice the EA set that is stored for the object on disk. It is a 
good idea to first perform a level 2 search to determine the size of the 
FAs that the file objects contain, and then perform the level 3 search 
with the correctly calculated buffer size. The buffer size can be calcu- 
lated following a level 2 search by using the following formula: 


sizeof (EAOP2) + sizeof(FILEFINDBUF3) + fea2list.cbList + (NumEAs * 3) 


The last part of the calculation is to account for pad bytes that may be 
necessary to doubleword-align the FEA2 strctures. 

ulResultBufLen - input 

The size, in bytes, of the buffer pointed to by pResultBuf The maxi- 
mum buffer size cannot be greater than 64k, otherwise unpredictable 
results may occur. 

pulSearchCount - input/output 
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On input, the number of matching file objects to return to the buffer 
pointed to by pResultBuf. On output, the actual number of file objects 
returned. 

ulFileInfoLevel - input 

Specify one of the following searches: 


Constant Description 

FIL_ STANDARD 1 Return level 1 file information. This is 
standard file information. 

FIL_QUERYEASIZE 2 Return level 2 file information. This 


includes information returned from a level 
1 search, plus the size of the specified EAs. 


FIL_QUERYEASFROMLIST 3 Returns level 2 information, plus the 
actual values of the requested EAs. 


RETURNS 
0 NO_ERROR 108 ERROR_DRIVE_LOCKED 
2 ERROR_FILE_NOT_FOUND 111 ERROR_BUFFER_ 
OVERFLOW 
3 ERROR_PATH_NOT_ 113 ERROR_NO_MORE_ 
FOUND SEARCH_HANDLES 


6 ERROR_INVALID_-HANDLE 206 ERROR_FILENAME_ 
EXCED_RANGE 

11 ERROR_BAD_FORMAT 208 ERROR_META_ 
EXPANSION_TOO_LONG 

18 ERROR_NO_MORE_FILES 254 ERROR_INVALID_ 


EA NAME 

26 ERROR NOT _DOS_DISK 255 ERROR EA LIST_ 
INCONSISTENT 

87 ERROR INVALID _ 275 ERROR EAS DIDNT_FIT 

PARAMETER 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 264 DLL: DOSCALLS 

SEE ALSO 


DosFindClose -113, DosFindNext -119, DosQueryFileInfo -103, 
DosQueryPathInfo -106, DosQuerySysInfo -109, DosSearchPath -129, 
DosSetFileInfo -80, DosSetPathInfo -87 
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NOTES 


Any nonzero return code, other than ERROR_EAS_DIDNT_FIT, indi- 
cates that no directory handle has been returned. The directory han- 
dle returned may be used on a subsequent call to DosFindNext. 
When ERROR EAS DIDNT _FIT is returned, the name of the EA 
that didn’t fit is returned as the first EA entry, and no other entries are 
returned even if they would fit in the buffer. The information returned 
for the EA that would not fit is in the format of a level 2 search buffer. 
The file name returned can be used in combination with the EA re- 
quest information used on the call to DosFindFirst to retrieve the EA 
data (that would not fit) into a larger buffer with DosQueryPathInfo. 


RESTRICTIONS/WARNINGS 


@ This API has been found to be unreliable (under OS/2 2.1) when 
used to retrieve EA data for files (a level 3 search). For example, the 
function will return EA information on a different EA that wasn’t 
specified on the request. Instead, it is recommended that a level 2 
search be performed and then use DosQueryPathInfo to retrieve 
the EA information. This makes processing a little slower, but far 
more reliable. 
The filtering peformed by the must-have attributes may not work 
correctly when peforming searches on LAN drives. Therefore, it is 
recommended that the application request files with any attribute, 
and then perform its own filtering. 
Level 3 searches do not cause the EA request to be used as part of 
the search criteria. The search criteria is only the file mask and file 
attributes. Level 3 searches just provide a one-step method of search- 
ing and retrieving EAs. 
@ When performing a level 3 search, the type of EA information re- 
turned may be set to zero even though the EA has a type of MVMT_ 
ASCII. Therefore, treat EA types of zero as ASCII EAs. 





DosFindNext File Management 


Continues a search started with DosFindFirst. 
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SYNTAX 


APIRET DosFindNext (HDIR hdirSearch, PVOID pResultBuf, ULONG 
ulResuliBufLen, PULONG pulSearchCount) 


PARAMETERS 


hdirSearch - input 

The directory handle returned from a previous call to DosFindFirst. 
pResultBuf - input/output 

The address of the buffer that was passed to DosFindFirst. For a level 3 
search, this buffer should contain the same input data that was used on 
the call to DosFindFirst, otherwise, unpredictable results will occur. 
ulResultBufLen - input 

The size, in bytes, of the buffer pointed to by pResultBuf 

pulSearch Count - input/output 

On input, the number of matching file objects to return to the buffer 
pointed to by pResultBuf. On output, the actual number of file objects 
found. 


RETURNS 

0 NO_ERROR 87 ERROR_INVALID_ 
PARAMETER 

6 ERROR_INVALID HANDLE 111 ERROR _BUFFER_ 
OVERFLOW 


18 ERROR_NO_MORE_FILES 275 ERROR_EAS DIDNT_FIT 
26 ERROR_NOT_DOS_DISK 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 265 DLL: DOSCALLS 

SEE ALSO 


DosFindClose -113, DosFindFirst -113, DosQueryFileInfo -103, 
DosQueryPathInfo -106, DosQuerySysInfo -109, DosSearchPath -129, 
DosSetFileInfo -80, DosSetPathInfo -87 


NOTES 


If the buffer is too small to hold the returned information, ERROR_ 
BUFFER OVERFLOW is returned. The next call to DosFindFirst will 


File Management Led 


begin with the same entry where the overflow occurred. Therefore, a 
larger buffer must be allocated to continue the search past the entry. 
ERROR_EAS_ DIDNT_FIT is returned when a level 3 search is being 
performed and the EAs would not fit in the specified buffer. The call 
will return information on the EA that would not fit, in the format of a 
level 2 search buffer. DosQueryPathInfo can be used to retrieve the 
FAs for the file object whose EAs would not fit by passing the file name 
returned and the same input buffer that was used on the call to 
DosFindFirst/ DosFindNext. The search can be continued with subse- 
quent calls to DosFindNext. 


Directory and Disk Functions 





DosCreateDir creates a subdirectory (pg. 121). 

DosDeleteDir removes an empty subdirectory (pg. 123). 
DosQueryCurrentDir returns the current directory of the calling 
process (pg. 124). 


DosQueryCurrentDisk returns the current disk of the calling process 





(pg. 125). 
DosSetCurrentDir sets the current directory of the calling process 
(pg. 126). 
DosSetDefaultDisk sets the default drive of the calling process 
(pg. 127). 

@ DosCreateDir File Management 


Creates a directory. 


SYNTAX 
APIRET DosCreateDir (PSZ pszDirName, PEAOP2 peaop2Bu/f) 


PARAMETERS 

pszDirName - input 

The address of a buffer containing the null-terminated name of the di- 
rectory to be created. This value may be a full path with the last subdi- 
rectory specified being the directory to be created. 
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peaop2Buf - input 

The address of an EAOP2 structure containing the EAs to be defined 
for the directory, or NULL to indicate no EAs will be defined for the 
directory. 

On input, the EAs are set based on the values specified in fpFEA2List, 
and the fpGEA2List field and oError fields are ignored. 

On output, the EAOP2 structure and the structures pointed to by the 
EAOP2 structured are left unchanged. If an error occurs when setting 
an EA, the offset of the FEA2 from the beginning of the FEA2 list that 
caused the error will be set in oEFrror. 


RETURNS 
0 NO_ERROR 108 ERROR DRIVE LOCKED 
3 ERROR PATH NOT _ 206 ERROR FILENAME __ 
FOUND EXCED_RANGE 
5 ERROR ACCESS DENIED 254 ERROR INVALID _ 
EA NAME 
26 ERROR NOT_DOS_DISK 255 ERROR EA LIST_ 
INCONSISTENT 
87 ERROR INVALID _ 256 ERROR EA LIST_ 
PARAMETER TOO_LONG 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 270 DLL: DOSCALLS 
SEE ALSO 


DosCopy -65, DosDeleteDir -123, DosMove -71, 
DosQueryCurrentDir -124, DosSetCurrentDir -126, 
DosSetPathInfo -87 


NOTES 


If pszDirName is a full path, then all directories in the path except the 
last one must exist, otherwise ERROR PATH NOT FOUND is re- 
turned. 

Applications should use DosQuerySysInfo to determine the maxi- 
mum path length, and allocate path buffers and restrict path names 
based on this value. 
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@ DosDeleteDir File Management 
Deletes empty subdirectories. 


SYNTAX 
APIRET DosDeleteDir(PSZ pszDirName) 


PARAMETERS 


pszDirName - input 
The address of a null-terminated string containing the name of the 
empty directory to be deleted. 


RETURNS 

0 NO_ERROR 26 ERROR NOT_DOS_DISK 

3 ERROR PATH NOT_FOUND 87 ERROR INVALID _ 

PARAMETER 

5 ERROR ACCESS DENIED 108 ERROR DRIVE _LOCKED 

16 ERROR CURRENT _ 206 ERROR FILENAME _ 
DIRECTORY EXCED_ RANGE 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 226 DLL: DOSCALLS 

SEE ALSO 


DosCopy -65, DosCreateDir -121, DosDelete -67, DosForceDelete -70, 
DosMove -71 


NOTES 


DosDeleteDir can only delete subdirectories that are empty. If the di- 
rectory to be deleted contains any files (even files that are hidden), the 
call will return ERROR ACCESS DENIED. 
DosDeleteDir can delete hidden, read-only, and system directories. 
DosDeleteDir cannot delete directories that are in use by any run- 
ning sessions. 
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@ DosQueryCurrentDir File Management 


Obtains the path component of the current directory for the calling 
process on the specified drive. 


SYNTAX 


APIRET DosQueryCurrentDir(ULONG wlDriveNumber, PBYTE pbCurr- 
PathBuf, PULONG pulCurrPathBufLen) 


PARAMETER: 


ulDriveNumber - input 

The drive number whose current directory is to be queried. A zero in- 
dicates the current drive, 1 indicates drive A, 2 indicates drive B, and 
so on. 

pbCurrPathBuf - output 

The address of a buffer to receive the null-terminated path of the cur- 
rent directory. 

pulCurrPathBufLen - input/output 

On input, the address of a ULONG containing the size of the buffer 
pointed to by pbCurrPathBuf, in bytes. 

On output, if the bufffer is too small, this will contain the size of buffer 
required to hold the path excluding the null terminator. 


RETURNS 

0 NO_ERROR 26 ERROR NOT _DOS_ DISK 

15 ERROR_INVALID_ DRIVE 108 ERROR DRIVE LOCKED 

21 ERROR NOT_READY 111 ERROR BUFFER __ 
OVERFLOW 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 274 DLL: DOSCALLS 

SEE ALSO 


DosQueryCurrentDisk -125, DosQuerySysInfo -109, 
DosSetCurrentDir -126, DosSetDefaultDisk -127 


NOTES 


The path returned does not include the drive letter, a beginning back- 
slash, or a trailing backslash. If the path is the root directory of the 
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drive, the buffer will be filled with a single null. DosQueryCurrentDisk 
should be used to retrieve the current disk. 


RESTRICTIONS/WARNINGS 


@ In some cases, the size value will be adjusted for errors that are not 
buffer-size related. For example, ERROR_NOT_READY will change 
the value pointed to by pulCurrPathBufLen to zero. 





DosQueryCurrentDisk File Management 


Retrieves the current default drive of the calling process and a drive 
map. 


SYNTAX 

APIRET DosQueryCurrentDisk(PULONG pulDriveNumber, PULONG 
pulLogicalDriveMap) 

PARAMETER 


pulDriveNumber - output 

The address of a ULONG that will receive the number that represents 
the current logical drive. 

pulLogicalMap - output 

The address of a ULONG that will receive the mapping of the logical 
drive. The logical drives correspond to the bit positions with a one-to- 
one mapping. For example, drive A is represented by bit 0, drive B by 
bit 1, and so on. If the bit is set, then the drive exists. 


RETURNS 
0 NO_ERROR 


OTHER INFO 


Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 275 DLL: DOSCALLS 


SEE ALSO 


DosQueryCurrentDir -124, DosSetCurrentDir -126, 
DosDosSetDefaultDisk -127 
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NOTES 
None 
DosSetCurrentDir File Management 


Sets the current directory of the calling process. 


SYNTAX 
APIRET DosSetCurrentDir(PSZ pszDirectory) 


PARAMETERS 

pszDirectory - input 

The address of a buffer that contains the null-terminated directory 
name to change to. 


RETURNS 
0 NO_ERROR 26 ERROR _NOT_DOS_DISK 
2 ERROR_FILE_NOT_FOUND = 87 ERROR_INVALID_ 


PARAMETER 
3 ERROR_PATH_NOT_FOUND 108 ERROR_DRIVE_LOCKED 
5 ERROR_ACCESS_ DENIED 206 ERROR_FILENAME_ 
EXCED_RANGE 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 255 DLL: DOSCALLS 

SEE ALSO 


DosQueryCurrentDir -124, DosQueryCurrentDisk -125, 
DosSetDefaultDisk -127, DosQuerySysInfo -109 


NOTES 


All members that make up the path must exist. 

If the directory pointed to by pszDirectory includes the drive letter 
of a drive other than the current drive, the path will still be set; how- 
ever, the call will not change the process to that drive. The process 
must call DosSetDefaultDisk to cause the new path to become active. 
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@ DosSetDefaultDisk File Management 





Sets the specified drive to be the current drive for the calling process. 


SYNTAX 
APIRET DosSetDefaultDisk(ULONG ulDriveNumber) 


PARAMETER 


ulDriveNumber - input 
The drive number to set as the current drive. A 1 specifies drive A, a 2 
specifies drive B, 3 is drive C, and so on. 


RETURNS 

0 NO_ERROR 15 ERROR INVALID DRIVE 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 220 DLL: DOSCALLS 

SEE ALSO 


DosError -30, DosQueryCurrentDir -124, DosQueryCurrentDisk -125, 
DosSetCurrentDir -126 


Environment and Path Functions 





DosScanEnv returns the value of a given environment variable (pg. 127). 
DosSearchPath searches a path for a given file (pg. 129). 





@ DosScanEnv File Management 


Scans the environment segment for a specified environment variable. 
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SYNTAX 
APIRET DosScanEnv(PSZ pszEnvVanable, PSZ * ppszResult) 


PARAMETERS 


pszEnvVariable - input 

The address of a buffer containing the null-terminated environment 
variable to search for, for example: DPATH. 

*bpszResult - output 

The address of a PSZ to which the system will point the first character 
of the value of the environment variable in the environment segment. 
For example: 


DPATH=C: \ANYPATH; 


*ppszResult will point to C\ANYPATH (assume C syntax). 


RETURNS 

0 NO_ERROR 203 ERROR ENVVAR_NOT_ 
FOUND 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 227 DLL: DOSCALLS 

SEE ALSO 


DosGetInfoBlocks -278, DosSearchPath -129 


NOTES 


The environment variable must exist in the calling process’ environ- 
ment segment. 

The application may use the pointer returned to modify the value 
of the environment variable. The total size of the environment may not 
safely exceed 64k. 


RESTRICTIONS/WARNINGS 


@ The case of the environment variable is significant. 
@ The LIBPATH cannot be located this way since it is not a part of the 
environment segment. 
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@® DosSearchPath File Management 


Searches along the specified path or an environment path for a file. 


SYNTAX 


APIRET DosSearchPath(ULONG wlOptions, PSZ pszPath, PSZ pszFile, 
PBYTE pbResultBuf, ULONG ulResultBufLen) 


PARAMETERS 
ulOptions - input 
Specify the following desired options: 


Constant Description 


SEARCH CUR_DIRECTORY 0x01 Causes the current directory to be 
searched before searching the 
specified path. 


SEARCH_ENVIRONMENT 0x02 Indicates that pszPath points to an 
environment variable that contains 
the paths to search. If this is not 
specified, then it is assumed that 
pszPath points to a list of semi- 
colon-delimited paths to search. 


SEARCH_INGORENETERRORS 0x04 Indicates that searching should 
continue to the next path in the 
list if the current path cannot be 
searched due to a network error 
(such as the server is down). If this 
option is not specified, searching 
will stop when a network error 
occurs, and the call will return an 
error. 


pszPath - input 

The address of a buffer containing the null-terminated string of a path or 
environment variable that points to a path. If an explicit path list is speci- 
fied, the paths must be semicolon delimited. For example (C syntax): 


“er\test?;\"*de\my path\s51)]7@\"sd:\dev" /* Note that paths with 


semicolons must be in quotes */ 
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If pszPath refers to an environment variable containing the path 
list, then only the variable name should be specified. For example: 


“DPATH” 


pszFile - input 

The address of a buffer containing the null-terminated file name to 
search for. If the file name contains metacharacters (wildcards), then 
the metacharacters remain in the result buffer. Otherwise, the fully 
qualified path of the file is returned. 

pbResultBuf - output 

The address of a buffer that will receive the null-terminated file name, 
if it is found. Metacharacters remain when specified in pszFile. 
ulResultBufLen - input 

The size, in bytes, of the buffer pointed to by pbResultBuf- 


RETURNS 
0 NO ERROR 87 ERROR INVALID _ 
PARAMETER 

1 ERROR INVALID _ 111 ERROR BUFFER _ 
FUNCTION OVERFLOW 

2 ERROR FILE NOT_ 203 ERROR ENVVAR_ 
FOUND NOT_FOUND 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 

Ordinal: 228 DLL: DOSCALLS 

SEE ALSO 


DosFindFirst -113, DosFindNext -119, DosQuerySysInfo -109, 
DosScanEnv -127 


NOTES 


This function works by performing a DosFindFirst call on a series of 
names built from pszPath and pszFile. DosSearchPath makes no attempt 
to validate the names that it builds. 

If the path to search is being obtained from an environment vari- 
able (SEARCH_ENVIRONMENT option specified), that variable must 
exist in the calling process’ enviroment segment. 
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RESTRICTIONS/WARNINGS 


@ When searching for a file via an environment variable, the case of 
the environment variable is significant and must match; otherwise, 
ERROR ENVVAR NOT FOUND will be returned. 

@ The case of the path returned may not be the actual case of the path 
on the hard disk. For example, a path that is actually all uppercased 
on the hard disk will be retuned in all lowercase searching for a file 
via an explicit path. 


File Management Structures 





oEntryNextOffset (ULONG) 0 
The number of bytes from the beginning of this structure to the beginning of the next 
DENA2 structure. 


fEA (BYTE) 4 
Only the following attribute may be specified: 


FEA _NEEDEA (0x80) 


Indicates the EA is critical, and the application cannot run correctly without it. Programs 
that do not have the NEWFILES attribute declaration in their module definition file will be 
prevented from accidentally deleting the EA; however, they are not prevented from deleting 
the file altogether. Applications with the NEWFILES attribute have no restrictions on what 
they can do to critical EAs. The NEWFILES attribute is the default for 32-bit applications. 


cbName (BYTE) 5 
The length of the name of the EA, in bytes. 

cbValue (USHORT) 6 
The size of the EA’s value, in bytes. 

szName (CHAR[1]) 8 


The name of the EA (at least 1 byte). 
Used by: DosEnumAttribute -101 
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fpGEA2List (PGEA2LIST 0 
A pointer to a buffer containing a GEA2LIST structure, followed by zero or more GEAQ2s. 


fpFEA2List (PFEA2LIST) 4 
A pointer to a buffer containing a FEA2LIST structure, followed by zero or more FEA2s. 
oError (ULONG) 8 


The offset from the beginning of the FEA2LIST to the FEA2 structure, or the GEA2LIST to 
the GEA2LIST structure that caused the error. 


Used by: DosFindFirst -113, DosFindNext -119, DosOpen -73, DosQueryFileInfo 
-103, DosQueryPathInfo -106, DosSetFileInfo -80, DosSetPathInfo -87 





day (USHORT :5) 0:0 
The day of the month. 
month (USHORT :4) 0:5 
The month of the year. 
year (USHORT :7) 1:0 


The number of years since 1980. 


Used by: The FILEFINDBUF and FILESTATUS structures. 





oEntryNextOffset (ULONG) 0 
The number of bytes from the beginning of this structure to the beginning of the next FEA2 
structure. 

fEA (BYTE) 4 


Only the following attribute may be specified: 
FEA_NEEDEA (0x80) 


Indicates the EA is critical, and the application cannot run correctly without it. Programs 
that do not have the NEWFILES attribute declaration in their module definition file will be 
prevented from accidentally deleting the EA; however, they are not prevented from deleting 
the file altogether. Applications with the NEWFILES attribute have no restrictions on what 
they can do to critical EAs. The NEWFILES attribute is the default for 32-bit applications. 
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cbName (BYTE) 5 
The length of the name of the EA, in bytes. 

cbValue (USHORT) | 6 
The size of the EA’s value, in bytes. 

szName (CHAR[1]) 8 


The name of the EA (at least 1 byte). 


Used by: DosFindFirst -113, DosFindNext -119, DosOpen -73, DosQueryFileInfo 
-103, DosQueryPathInfo -106, DosSetFileInfo -80, DosSetPathInfo -87 





cbList (ULONG) 0 
The length of the FEA2 list, in bytes. The length is the sum of all the FEA2 structures start- 
ing with the one that is a part of this structure. 


list (FEA2[1]) 4 
An FEA2 structure. Any additional FEA2 structures should begin at the nearest doubleword 
boundary following this structure. 


Used by: DosFindFirst -113, DosFindNext -119, DosOpen -73, DosQueryFileInfo 
-103, DosQueryPathInfo -106, DosSetFileInfo -80, DosSetPathInfo -87 





fdateCreation (FDATE) 0 
An FDATE structure containing the date the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


ftimeCreation (FTIME) Z 
An FTIME structure containing the time the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


fdateLastAccess (FDATE) 4 
An FDATE structure containing the date the file was last accessed. This structure will be ze- 
roed out if the file is on a FAT partition. 


ftimeLastAccess (FTIME) 6 
An FTIME structure containing the time the file was last accessed. This structure will be ze- 
roed out if the file is on a FAT partition. 
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fdateLastWrite (FDATE) 8 
An FDATE structure containing the date the file was last modified. 
ftimeLastWrite (FTIME) 10 
An FTIME structure containing the time the file was last modified. 
cbFile (ULONG) LZ 
The size of the file, in bytes. 
cbFileAlloc (ULONG) 16 
The actual number of bytes used to store the file on the hard disk. 
attrFile (ULONG) 20 
The attributes of the file object. The following attrributes are valid: 
Constant Description 
FILE_NORMAL 0x00 The file object has no attributes. 
FILE_READONLY 0x01 The file is read-only. 
FILE_HIDDEN 0x02 The file object is hidden. 
FILE_SYSTEM 0x04 The file object is a system file object. 
FILE_DIRECTORY Oxl0 The file object is a directory. 
FILE_ARCHIVE 0x20 The file object has been modified since it was last 
archived. 
cchName (UCHAR) 22 
The length of the file name, in bytes. 
achName (CHAR[CCHMAXPATHCOMP]) 23 


The fully qualified path name of the file object. 
Used by: DosFindFirst -113, DosFindNext -119 





fdateCreation (FDATE) 0 
An FDATE structure containing the date the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


ftimeCreation (FTIME) 2 
An FTIME structure containing the time the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


File Management 135 


fdateLastAccess (FDATE) 4 
An FDATE structure containing the date the file was last accessed. ‘This structure will be ze- 
roed out if the file is on a FAT partition. 


ftimeLastAccess (FTIME) 6 
An FTIME structure containing the time the file was last accessed. ‘This structure will be ze- 
roed out if the file is on a FAT partition. 


fdateLastWrite (FDATE) 8 
An FDATE structure containing the date the file was last modified. 
ftimeLastWrite (FTIME) 10 
An FTIME structure containing the time the file was last modified. 
cbFile (ULONG) 12 
The size of the file, in bytes. 
cbFileAlloc (ULONG) 16 
The actual number of bytes used to store the file on the hard disk. 
attrFile (ULONG) 20 
The attributes of the file object. The following attributes are valid: 
Constant Description 
FILE_NORMAL 0x00 The file object has no attributes. 
FILE_READONLY 0x01 The file is read-only. 
FILE_HIDDEN 0x02 The file object is hidden. 
FILE_SYSTEM 0x04 The file object is a system file object. 
FILE_DIRECTORY Oxl0 The file object is a directory. 
FILE_ARCHIVE 0x20 The file object has been modified since it was last 
archived. 
cbList (ULONG) ne 


The total size of the EAs attached to the file object. This value can be used to allocate a 
buffer for an FEA2LIST that will be filled in by a call to DosQueryFileInfo or DosQuery- 
PathInfo to hold a file object’s EA set. This value can then be specified for the cbList field of 
the FEA2LIST structure. 


cchName (UCHAR) 26 
The length of the file name, in bytes. 
achName (CHAR[CCHMAXPATHCOMP]) 27 


The fully qualified path name of the file object. 


136 OS/2® Warp Control Program API 


Used by: DosFindFirst -113, DosFindNext -119 





lOffset (LONG) 0 
The byte offset from the beginning of the file. 
IRange (LONG) 4 


The length of the lock/unlock region, in bytes, beginning with /Offset. 
Used by: DosCancelLockRequest -Appendix A, DosSetFileLocks -82 





fdateCreation (FDATE) 0 
An FDATE structure containing the date the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


ftimeCreation (FTIME) 2 
An FTIME structure containing the time the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


fdateLastAccess (FDATE) 4 
An FDATE structure containing the date the file was last accessed. This structure will be ze- 
roed out if the file is on a FAT partition. 


ftimeLastAccess (FTIME) 6 
An FTIME structure containing the time the file was last accessed. This structure will be ze- 
roed out if the file is on a FAT partition. 


fdateLastWrite (FDATE) 8 
An FDATE structure containing the date the file was last modified. 

ftimeLastWrite (FTIME) 10 
An FTIME structure containing the time the file was last modified. 

cbFile (ULONG) 12 
The size of the file, in bytes. 

cbFileAlloc (ULONG) 16 
The actual number of bytes used to store the file on the hard disk. 

attrFile (ULONG) 20 


The attributes of the file object. The following attributes are valid: 
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Constant Description 
FILE_NORMAL 0x00 The file object has no attributes. 
FILE_READONLY 0x01 The file is read-only. 
FILE_HIDDEN 0x02 The file object is hidden. 
FILE_SYSTEM 0x04 The file object is a system file object. 
FILE_DIRECTORY Oxl0 The file object is a directory. 
FILE_ARCHIVE 0x20 The file object has been modified since it was last 

archived. 


Used by: DosQueryFileInfo -103, DosQueryPathInfo -87 





fdateCreation (FDATE) 0 
An FDATE structure containing the date the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


ftimeCreation (FTIME) Z 
An FTIME structure containing the time the file was created. This structure will be zeroed 
out if the file is on a FAT partition. 


fdateLastAccess (FDATE) 4 
An FDATE structure containing the date the file was last accessed. This structure will be ze- 
roed out if the file is on a FAT partition. 


ftimeLastAccess (FTIME) 6 
An FTIME structure containing the time the file was last accessed. This structure will be ze- 
roed out if the file is on a FAT partition. 


fdateLastWrite (FDATE) 8 
An FDATE structure containing the date the file was last modified. 

ftimeLastWrite (FTIME) 10 
An FTIME structure containing the time the file was last modified. 

cbFile (ULONG) 12 
The size of the file, in bytes. 

cbFileAlloc (ULONG) 16 


The actual number of bytes used to store the file on the hard disk. 
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attrFile (ULONG) 


20 


The attributes of the file object. The following attributes are valid: 


Constant 
FILE_NORMAL 0x00 
FILE_READONLY 0x01 
FILE_HIDDEN 0x02 
FILE_SYSTEM 0x04 
FILE_DIRECTORY 0x10 
FILE_ARCHIVE 0x20 


cbList (ULONG) 


Description 
The file object has no attributes. 
The file is read-only. 
The file object is hidden. 
The file object is a system file object. 
The file object is a directory. 


The file object has been modified since it was last 
archived. 


22 


The total size of the EAs attached to the file object. This value can be used to allocate a 
buffer for an FEA2LIST that will be filled in by a call to DosQueryFileInfo or DosQuery- 
PathInfo to hold a file object’s EA set. This value can then be specified for the cbList field of 


the FEA?LIST structure. 


Used by: DosQueryFileInfo -103, DosQueryPathInfo -106 





twosecs (USHORT :5) 


The number of seconds. 


minutes (USHORT :6) 


The number of minutes. 


hours (USHORT :5) 


The number of hours. 


0:0 


0:5 


1:2 


Used by: The FILEFINDBUF and FILESTATUS structures. 





oEntryNextOffset (ULONG) 


0 


The number of bytes from the beginning of this structure to the beginning of the next 
GEA2 structure. GEA2 structures must be aligned on doubleword boundaries. 
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cbName (BYTE) 4 
The length of the name of the EA, in bytes. 
szName (CHAR[1]) 5 


The name of the EA (at least 1 byte). 


Used by: DosFindFirst -113, DosFindNext -119, DosOpen -73, DosQueryFileInfo 
-103, DosQueryPathInfo -106, DosSetFileInfo -80, DosSetPathInfo -87 





cbList (ULONG) 0 
The length of the GEA2 list, in bytes. The length is the sum of all the GEA2 structures start- 
ing with the one that is a part of this structure. 


list (GEA2[1]) 4 
A GEA2 structure. Any additional GEA2 structures should begin at the nearest doubleword 
boundary following this structure. 


Used by: DosFindFirst -113, DosFindNext -119, DosQueryFileInfo -103, 
DosQueryPathInfo -106 


Extended Attribute Data Types 





The following table contains a list of system defined EA data types and their format. The 
first WORD of each EA must specify its data type. 


Data Type Value Description Format 
EAT _ BINARY OxFFFE Binary data. EAT BINARY Length Data 
WORD WORD 
EAT ASCII OxFFFD ASCII data. EAT ASCII Length Data 
No null WORD WORD 


terminator. 


EAT_BITMAP OxFFFB Bitmap data. EAT_BITMAP Length Data 
WORD WORD 


EAT _METAFILE OxFFFA Metafile data EAT_METAFILE Length Data 
WORD WORD 
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EAT ICON 


EAT _EA 


EAT MVMT 


EAT_MVST 


EAT_ASNI 


OxFFF9 


OxFFEE 


OxFFDF 


OxFFDE 


OxFFDD 


Icon data. 


The name of 
another EA 


in the file that 


should be 
included in 


the current EA. 


Multiple value, 


multiple 
type data. 


Multiple value, 


single type 
data. 


Indicates the 
EA uses the 
ASN.I ISO 
standard to 


describe multiple 
value data streams. 


EAT ICON 
WORD 


EAT EA 
WORD 


EAT_MVMT 
WORD 


EAT _MVST 
WORD 


EAT_ASNI 
WORD 


Length 
WORD 


Length 
WORD 


Code- 


page 
WORD 


Code- 


page 
WORD 


Data 


Data 


Data 


Num of 
Entries 
WORD 


Num of 
Entries 
WORD 


{Data 


type 
Data] 


Data 


type 
[Data] 


The user can define his or her own data types in the hex range of 0x0000 through 7FFF. The 
range above 0x8000 is reserved. All user-defined data types should be preceded with a 
WORD containing their length. 


Standard Extended Attributes (SEAs) 


The system prefixes all of the predefined EAs with a period (.). Predefined EAs are referred 
to as standard extended attributes (SEAs), and are primarily used and manipulated via the 
Workplace Shell. Users should never name their own EAs with a dot prefix. The following 
SEAs are defined: 


AASSOCTABLE (MVMT) 
LONGNAME (ASCII) 
HISTORY (MVMT) 
VERSION (ASCII | BINARY) 


KEYPHRASES (MVST) 
‘COMMENTS (MVMT) 
TYPE (MVMT) 


.CODEPAGE (BINARY) 
SUBJECT (ASCID) 


ICON (ICON) 


The system users should never prefix the names of their EAs with a period. 





lle System 





A ccess to mass storage devices such as hard disks and floppy disks is 

anaged by a file system. ‘The file system manages file I/O and the 
format of the stored data. OS/2 allows multiple file systems to be in- 
stalled and active at the same time via its installable file system archi- 
tecture. OS/2 includes one built-in file system, File Allocation Table 
(FAT), and one installable file system, High Performance File System 
(HPES). 

Hard disks are organized into one or more primary or extended 
partitions. Each partition is assigned a drive letter to distinguish it 
from the other partitions; extended partitions are referred to as logical 
drives. Each partition is referred to as a volume, which may optionally 
be labeled. The system will automatically asign a volume serial number 
to each volume. 

When there are outstanding I/O requests to a drive, the system 
will use a combination of the volume label and serial number to deter- 
mine whether the medium in the drive has changed. If the medium 
has changed, then the system signals the critical error handler to 
prompt the user for the volume that has the correct serial number and 
label. This connection is maintained until all open files on the drive 
are closed, the cache buffer references are flushed, and all search ref- 
erences are removed. The system will determine the file system type, 
volume, and serial number only when the medium changes. 


14] 
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Volumes are divided into directories and files. Every volume has a 
root directory with one or more subdirectories beneath it. Each direc- 
tory contains entries that indicate its contents. The entries identify 
whether the item is a file or directory as well as relevant information 
for those items such as size, attributes, and date of last access. Different 
file systems may have other information defined as well. 

File systems are designed to allow applications to transparently re- 
fer to certain nondisk devices as if they were files. Nondisk devices are 
opened like files, with the exception that the name of the device is 
used to perform the open request. For example, the printer can be 
opened for writing by specifying its logical name—PRN. The following 
is an inconclusive list of device names reserved by OS/2: 


CLOCK$ Clock. 


COM1 - COM4 Serial ports 1 through 4. Reserved only when the 
asynchronous device driver is loaded. If LAN software 
is installed, COM1-COM9 may be reserved. 


CON Console keyboard and screen. 

KBD$ Keyboard. 

LPT1 - LPT3 Parallel printer ports 1 through 3. If LAN software is 
installed, LPT1- LPT9 may be reserved. 

MOUSE$ Mouse. Reserved only when a mouse device driver is 
loaded. 

NUL Null or dummy device. 

POINTER$ Pointer draw device (references the mouse on the 
screen). Reserved only when a mouse device driver is 
loaded. 

PRN Default printer, usually LPT1. 

SCREEN$ Screen. 


Applications should never name files the same as a reserved de- 
vice name, since OS/2 always checks for an existing device name be- 
fore a file name. 


FAT File System 


The FAT file system used by OS/2 is based on the DOS FAT file system, 
and is fully compatible with that system. In addition, OS/2 has im- 
proved on the FAT file system to support caching and lazy writing. 
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The FAT file system is a hierarchical file system which supports the 
concept of directory trees. The FAT system limits file and directory 
names to 8 characters for the name, and 3 characters for an extension 
with a period (.) separating the two. File names on FAT systems can 
contain the following characters: 


A-Z1-9$%>~-_ @{}~*°!#() 


Blanks trailing the file name/directory name or extension are not 
significant since FAT automatically pads unused training space with 
blanks. Blanks anywhere else in the file name/directory name or ex- 
tension are significant. FAT ignores case, and file names returned by 
file system functions will be in uppercase. 


High Performance File System 


HPFS is the only installable file system included with OS/2. It is hier- 
archical like FAT, but has numerous enhancements, many of which can 
improve the performance of file management: 


Caching of directories, data, and file system data structures. 
Multithreaded I/O. 

Write-behind logic (referred to as lazy write). 

Optional write-through logic. 

Strategic allocation of directory structures. Directories are stored in 
a binary tree format for fast access. 

Reduced fragmentation file allocation. 

Enhanced recoverability. 

Superior extended attribute support. 

Long file name support (255 characters). 

Can boot OS/2 from an HPFS disk. 


HPFS file and directory names can contain up to 255 characters 
(including the null terminator). A fully qualified path (drive, direc- 
tory, and file name) can be up to 260 characters including a null ter- 
minator. HPFS file and directory names may contain the following 
characters: 


A-Z0-9$%~-_@{}~°>!#()+#=;,[]. space 


These characters may be used multiple times anywhere within a file 
name or directory name; however, periods and spaces at the end of a 
file name or directory name are ignored. HPFS preserves case for di- 
rectory listings, but case is ignored for all other file system operations 
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(file searches). This treatment of case precludes the naming of two 
files with the same name if the only difference is their case. There is no 
requirement for file extensions in HPFS, and files on HPFS drives can 
have multiple file extensions. 

HPES is optimized for large disk partitions and partitions contain- 
ing a large number of directory and/or file entries. To improve per- 
formance, HPFS utilizes a memory cache that is divided into blocks of 
2k. All data read from and written to an HPFS volume is transferred 
through the cache. The cache uses a “least recently used” algorithm to 
determine which data must be flushed from the cache to make room 
for new data. 

In addition to the cache, HPFS will often write data to disk as a 
background task to improve performance. The data is written to disk 
when there is disk idle time or when a certain amount of time has 
elapsed. There are three options on the CACHE statement in the con- 
fig.sys that allow configuration of the lazy-write option. The DISKIDLE 
option specifies the number of milliseconds that may elapse on an idle 
disk before cache blocks that have not been touched for BUFFERIDLE 
milliseconds are queued for writing to disk. The MAXAGE option 
specifies the number of milliseconds that may elapse before data is 
moved from one section of cache memory to another. The move oper- 
ation places data that has not been recently accessed in a least-recently- 
used section of the cache. 


Routing File System Requests 


When an application uses a file system function to access media on a 
device, the system first checks to see if there in an installable file system 
managing the device. If not, then the built-in FAT file system will han- 
dle the request. If the format of the media on the device is not under- 
stood by the FAT file system, it will return an error. 


Local and Remote File Systems 


File systems used with a local device are referred to as local file systems. 
A file system that is located on a remote device (such as a disk on a 
LAN server) is referred to as a remote file system. Applications can use 
DosFSAttach to establish or discontinue connections with local or re- 
mote file systems. In general, all local file systems are automatically at- 
tached by the system at boot time. 
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The system uses a block device driver to handle I/O on local file 
systems. For remote file systems, the system uses a device driver that ac- 
cesses a network or communications device. Typically, an installable 
file system is written for connections to remote devices that allows 
those devices to be accessed as if they were local. DosFSAttach may be 
used to attach a remote file system and assign a drive letter to it. 


File System Functions 





DosFSAttach attaches or detaches a drive to or from a remote file sys- 
tem device, or a pseudocharacter device name to or from a local or re- 
mote file system device (pg. 145). 

DosFSCtl communicates with a file system driver (pg. 147). 
DosQueryFSAttach obtains information about an attached file system 
(pg. 150). 

DosQueryFSInfo obtains information about a volume (pg. 152). 
DosResetBuffer flushes cache buffers to disk (pg. 153). 

DosSetFSInfo sets volume information (pg. 154). 

DosShutdown prepares the attached file systems for shutdown 





(pg. 155). 
@ DosFSAttach File System 


Attaches or detaches a drive to or from a remote file system device, or 
a pseudocharacter device name to or from a local or remote file system 
device. 


SYNTAX 

APIRET DosFSAttach (PSZ pszDeviceName, PSZ pszFSDriverName, 
PVOID pArgbuffer, ULONG ulArgBufLen, 
ULONG wlObperation) 


PARAMETERS 

pszDeviceName - input 

Specify either a driver letter, pseudocharacter device name, or a 
spooled device. Drive designations are null-terminated strings con- 
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taining a drive name followed by a colon. All operations performed 
with the drive will be routed to the file system driver specified in 
pszFSDriverName. 

Pseudocharacter devices (or single file devices) are null-termi- 
nated strings containing subdirectory \DEV\ followed by the device 
name. Any operations performed on that device are routed to the file 
system driver specified in pszkSDriverName. 

Spooled devices are null-terminated strings containing the name 
of the spooled device. The file system driver will not see requests to 
spooled devices. 
pszFSDriverName - input 
A null-terminated string containing the name of the remote file system 
driver to be attached or detached. If ulOperation equals FS_SPOOLAT- 
TACH or FS_SPOOLDETACH, then specify NULL. 
pArgBuffer - input 
When ulOperation equals FS_ATTACH or FS_DETACH, the address of 
a buffer containing the file system driver argument. The data is in the 
form of null-terminated strings prefixed with a WORD containing the 
number of strings in the buffer. This data is specific to a particular file 
system driver. 

When ulOperation equals FS_SPOOLATTACH, the format of the 
buffer is as follows: 

hpNamedPipe (ushort) 

The handle of the named pipe opened by the spooler. 
cbSpoolObj (byte) 

The length, in bytes, of the spooler object. 
szSpoolObj (uchar) 

The null-terminated name of the spooler object. 

When wlOperation equals FS_SPOOLDETACH, this value should 
be NULL. 
ulArgBufLen - input 
The length, in bytes, of the data pointed to by pArgBuffer. 
ulOperation - input 
Specify one of the following operations to perform: 


Operation Description 

FS_ATTACH Q Attach a drive or pseudocharacter device. 
FS_ DETACH 1 Detach a drive or pseudocharacter device. 
FS_SPOOLATTACH 2 Attach a spooled device. 


FS_SPOOLDETACH 3 Detach a spooled device. 
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RETURNS 
0 NO_ERROR 124 ERROR INVALID LEVEL 
8 ERROR NOT _ENOUGH_ 252 ERROR INVALID _ 
MEMORY FSD_NAME 
15 ERROR INVALID DRIVE 253 ERROR INVALID PATH 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 269 DLL: DOSCALLS 
SEE ALSO 


DosFSCtrl -147, DosQueryFSAttach -150 


RESTRICTIONS/WARNINGS 

@ This call cannot be used to redirect the drive letters of local drives. 

@ This call can only establish connections with drives or devices in the 
system's name space. 





DosFSCtl File System 


Performs low-level communication with a file system driver. 


SYNTAX 


APIRET DosFSCtl(PVOID plnOutData, ULONG ulMaxOutData, 
PULONG pulDataLenInOut, PVOID pParmList, 
ULONG wlParmLenMax, PULONG pulParm- 
LenInOut, ULONG wlFunctionCode, PSZ pszRoute- 
Name, HFILE Affile, ULONG ulRouteMethod) 


PARAMETERS 


plnOutData - input/output 

The address of the data area to receive the information returned by 
the file system driver. 

ulMaxOutData - input 

The size, in bytes, of the buffer pointed to by plnOutData. 
pulDataLenInOut - input/output 

On input, the address of a ULONG that contains the size, in bytes, of 
the data pointed to by plnOutData. This value cannot exceed the size 
value specified in ul/MaxOutData. On output, the address of a ULONG 
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that contains the size, in bytes, of the data returned by the file system 
driver in plnOutData. If this call returns ERROR_BUFFER_OVER- 
FLOW, then the value indicates the size of the buffer, in bytes, re- 
quired to hold the data returned by the file system driver. 

pParmList - input/output 

The address of the command-specific parameter list. 

ulParmLenMax - input 

The size, in bytes, of the buffer pointed to by pParmList. 
pulParmLenInOut - input/output 

On input, the address of a ULONG that contains the size, in bytes, of 
the data pointed to by pParmList. This value cannot exceed the size 
value specified in ulParmLenMax. On output, the address of a ULONG 
that contains the size, in bytes, of the parameters returned by the file 
system driver in pParmLust. If this call returns ERROR_BUFFER_ 
OVERFLOW, then the value indicates the size of the buffer, in bytes, 
required to hold the parameters returned by the file system driver. 
ulFunctionCode - input 

The file system driver-specific function code to execute. Remote file 
system drivers can have two different types of functions: locally han- 
dled functions, and functions that are exported across the network. A 
function code with hex bit 4000 set indicates that the remote file sys- 
tem driver should export the function. 

The following function code ranges are defined: 


0x0000 to Ox7FFF — Reserved for use by the operating system. 

0x8000 to OxBFFF Local file system driver functions. 

OxC000 to OxFFFF — Exported file system driver functions. 
Additionally, the following function codes may be specified: 

Constant Description 


FSCTL_ERROR_INFO 1 Requests error code information from the 
file system driver. On input, the error code 
on which to request information is passed to 
the file system driver in the first word of the 
pParmList bufter. 


FSCTL_MAX_EASIZE 2 Requests the maximum individual EA size 
and maximum size of the complete EA list 
supported by the file system driver. On 


return, the p/nOutData will contain an 
EASIZEBUF structure. 
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pszRouteName - input 

The address of a null-terminated string containing the name of a file 
system driver, file, or directory that the operation applies to. If routing 
is performed via file handle, then pszRouteName must be NULL. 

hfFile - input 

When wlRouteMethod is FSCTL_HANDLE, the file handle of a file or de- 
vice, otherwise -l. 

ulRouteMethod - input 

Indicate the routing method to be applied to the value specified in 
pszRouteName as follows: 


Constant Description 


FSCTL_HANDLE 1 The function will be directed via the file 
handle specified in hfFile. The file system 
driver associated with the file handle will 


process the request. pszRouteName must be 
NULL. 


FSCTL_PATHNAME 2 pszRouteName refers to a path name that 
directs routing. The path may be a drive 
letter, a relative path, or a full path. The file 
system driver associated with the drive that 
the path is located on will process the 
request. Affile must be set to -1. 


FSCTL_FSDNAME 3 pszRouteName refers to the name of a file 
system driver. The named file system driver 
will process the request. h/File must be -1. 


RETURNS 
0 NO_ERROR 111 ERROR BUFFER _ 
OVERFLOW 
1 ERROR _INVALID _ 117 ERROR _INVALID_ 
FUNCTION CATEGORY 
6 ERROR_INVALID_-HANDLE 124 ERROR INVALID LEVEL 
87 ERROR INVALID _ 252 ERROR INVALID _ 
PARAMETER FSD_NAME 
95 ERROR INTERRUPT 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSFILEMGR 


Ordinal: 285 DLL: DOSCALLS 
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SEE ALSO 
DosFSAttach -145 


NOTES 


None 





@ DosQueryFSAttach File System 


Returns information about an attached local or remote file system, 
character device, or pseudocharacter device. 


SYNTAX 


APIRET DosQueryFSAttach (PSZ pszDeviceName, ULONG ulOrdinal, 
ULONG wif SInfoLevel, PFSQBUFFER2 
pfsq2Info, PULONG pulBufferLen) 


PARAMETERS 

pszDeviceName - input 

Specify either a driver letter, character device name, or pseudocharacter 
device name. Drive designations are null-terminated strings containing 
a drive name followed by a colon. Character or pseudocharacter devices 
are null-terminated strings containing the subdirectory \DEV\ followed 
by the device name. If ulFSInfoLevelis set to either FSATL_DEVNUMBER 
or FSAIL_DRVNUMBER, then this parameter is ignored. 

ulOrdinal - input 

An index into the list of character or pseudocharacter devices or set of 
drives. The ordinal is 1-based. The ordinal position of an item in a list 
has no significance, since the ordinal is used only to step through the 
list. The mapping for ordinals to an item is volatile, and may change 
from call to call. This parameter is ignored if FSAIL_QUERYNAME is 
specified for wl SInfoLevel. 

ulFSInfoLevel - input 

Specify one of the following query options: 


Constant Description 


FSAIL_QUERYNAME 1 Returns information based on the drive or 
device name specified in pszDeviceName. ‘The 
ulOrdinal parameter is ignored. 
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FSAIL_ DEVNUMBER 2 Returns information about a character or 
pseudocharacter device based on the value 
of ulOrdinal. The pszDeviceName parameter is 
ignored. 


FSAIL_ DRVNUMBER 3 Returns information about a drive based on 
the value of wlOrdinal. The pszDeviceName 
parameter is ignored. 


pfsq2Info - output 

The address of a FFQBUFFER2 structure that will receive the informa- 
tion returned from the query. 

pulBufferLen - input/output 

On input, the address of a ULONG that contains the size, in bytes, of 
the buffer pointed to by pfsq2Info. On output, the address of a ULONG 
that contains the size, in bytes, of the information returned in the 
buffer pointed to by pfsg2Info. 


RETURNS 
0 NO_ERROR 111 ERROR BUFFER_ 

OVERFLOW 

15 ERROR INVALID DRIVE 124 ERROR INVALID LEVEL 

21 ERROR NOT_READY 259 ERROR NO MORE ITEMS 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSFILEMGR 

Ordinal: Zhi DLL: DOSCALLS 

SEE ALSO 


DosFSAttach -145, DosQuerySysInfo -109 


NOTES 


This function may be used by applications to determine the file system 
attached to a drive so that data will not be written to a drive by the in- 
correct file system driver. This can occur when the file system that 
should be used with the drive has not been loaded by the system, and 
the system attaches a default file system to the disk that is incompatible 
with the data. 

If file system drivers for a device refuse to mount, the device will be 
attached to the resident file system (which is FAT). 
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RESTRICTIONS/WARNINGS 

@ The information returned by this function call can change fre- 
quently, therefore, the information returned by this call may be in- 
valid before it is returned. 





DosQueryFSIinfo File System 


Returns information about a file system device. 


SYNTAX 


APIRET DosQueryFSInfo (ULONG wlDriveNum, ULONG 
ulfSInfoLevel, PVOID pFSInfoBuf, ULONG 
ul SInfoBufSize) 


PARAMETERS 

ulDriveNum - input 

The number of the logical drive to query. This value can range from 0 
through 26. If 0 is specified, then information about the current drive 
is retrieved. Otherwise, 1 begins with drive A, 2 is drive B, and so on. 
When a logical drive is specified, the media in the drive and the re- 
quest is passed to the file system driver responsible for that media or to 
the file system driver attached to the drive. 

ulF SInfoLevel - input 

Specify the level of information to retrieve: 


Constant Description 
FSIL_ALLOC 1 Return level 1 (allocation) information. 
FSIL_VOLSER 2 Return level 2 (volume) information. 


pFSInfoBuf - output 

The address of a buffer that will receive the information returned. If 
level 1 information is requested, this buffer will contain an FSALLO- 
CATE structure. For level 2 information the buffer will contain the fol- 
lowing data: 


VolumeSerialNumber (ULONG): The volume serial number. 

VolumeLabelLength (BYTE): The length of the volume label, sans 
NULL. The length returned will be no longer than 11 bytes. 

VolumeLabel (CHAR[ ]): The null-terminated volume label. 


File System 153 


ulFSInfoBufSize - input 
The size, in bytes, of the buffer pointed to by pFS/nfoBuf: 


RETURNS 


0 NO_ERROR 111 ERROR_BUFFER _ 
OVERFLOW 
15 ERROR_INVALID_DRIVE 124 ERROR_INVALID_ LEVEL 
21 ERROR_NOT_READY 


OTHER INFO 

Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 278 DLL: DOSCALLS 

SEE ALSO 


DosSetFSInfo -154 


NOTES 


If the specified drive is not loaded with a disk, then ERROR_NOT_ 
READY is returned. 

The volume serial number and volume label are used by the hard 
error popups when requests are made to an unmounted drive. The 
volume label is a unique 32-bit number assigned by the operating sys- 
tem. If a disk has no volume serial number, then zero is returned for 
the volume serial number. If the disk has no volume label, then a 
length of zero is returned for the volume label length, and no error is 
returned. 





DosResetBuffer File System 


Flushes cache buffers to disk. 


SYNTAX 
APIRET DosResetBuffer (HFILE h/File) 


PARAMETERS 
hfFile - input 
The handle of the file whose buffers will be flushed to disk. If OxFFFF 


is specified, then all the buffers of all of the files of the calling process 
are flushed to disk. 
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RETURNS 

0 NO_ERROR 5 ERROR ACCESS DENIED 
2 ERROR_FILE_NOT_FOUND 6 ERROR_INVALID HANDLE 
OTHER INFO 

Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 254 DLL: DOSCALLS 

SEE ALSO 


DosClose -220, DosOpen -223, DosWrite -227 


NOTES 


This function flushes the target file’s buffers to disk and updates the 
file’s directory information as if the file were closed. 





DosSetFSInfo File System 


Sets the volume information for file system devices. 


SYNTAX 


APIRET DosSetFSInfo(ULONG ulDriveNum, ULONG ulFSInfoLevel, 
PVOID pF SInfoBuf, ULONG ullnfoBufSize) 


PARAMETERS 

ulDriveNum - input 

The logical drive number of the volume whose label will be set. Zero 
indicates the current drive, 1 represents drive A, 2 is drive B, and so on. 
If OxFFFF is specified, then pfS/nfoBuf contains the null-terminated 
path name of the file system driver. 

ulFSInfoLevel - input 

Specify the level of information to set. This must be FSIL_VOLSER (2). 
pFSInfoBuf - input 

The address of a buffer containing the information to be set. Specify 
level 2 information as follows: 


Byte Description 
] The length, in bytes, of the volume label excluding the null. 


2 The null-terminated volume label. 
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ullnfoBufSize - input 
The size, in bytes, of the buffer pointed to by pFSInfoBuf. 


RETURNS 

0 NO_ERROR 122 ERROR INSUFFICIENT _ 
BUFFER 

15 ERROR INVALID DRIVE 123 ERROR _ INVALID NAME 

21 ERROR NOT_READY 124 ERROR INVALID LEVEL 

82 ERROR CANNOT _MAKE 154 ERROR LABEL TOO_ 
LONG 

OTHER INFO 

Include file: bsedos.h Define: INCL DOSFILEMGR 

Ordinal: Dee DLL: DOSCALLS 

SEE ALSO 


DosQueryCurrentDisk -125, DosQueryFSInfo -152, 
DosQuerySysInfo -109, DosSetDefaultDisk -127 


NOTES 


Trailing blanks specified for volume labels are ignored. 
This call may be used only on volumes where write access is per- 
mitted. 


RESTRICTIONS/WARNINGS 


8 Applications cannot set the volume serial number. 





DosShutdown File System 


Locks out file system changes and flushes all file system buffers to disk. 


SYNTAX 
APIRET DosShutdown(ULONG wilReserved) 


PARAMETERS 


ulReserved - input 
This is a reserved parameter and must be set to zero. 
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RETURNS 


0 NO_ERROR 274 ERROR_ALREADY_ 
SHUTDOWN 
87 ERROR_INVALID_PARAMETER 


OTHER INFO 


Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 415 DLL: DOSCALLS 


SEE ALSO 
WinShutdownSystem 


NOTES 


When DosShutdown returns successfully, the system may be safely pow- 
ered off or rebooted. 


RESTRICTIONS/WARNINGS 


® This call is not friendly to Presentation Manager (PM) applications 
or the Workplace Shell. Whenever possible, applications should call 
WinShutdownSystem instead. WinShutdownSystem will send WM_ 
SAVEAPPLICATION and WM_QUIT messages to any open win- 
dows. This allows Workplace Shell and other PM applications to save 
their window positions (and other information) and terminate 
gracefully. 

e@ Any functions that attempt to change file system data after invoking 
this call will either return with ERROR ALREADY SHUTDOWN, 
or will block permanently and never return. 

@ Once this call is issued, no new memory can be allocated on the sys- 
tem. Therefore, the application should allocate all the memory it 
will possibly need before calling DosShutdown. 

@ The shutdown operation may take some time to complete. 
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File System Structures 





idFileSystem (ULONG) 0 
The file system ID. 

cSectorUnit (ULONG) 4 
The number of sectors per allocation unit. 

cUnit (ULONG) 8 
The total number of allocations units on the drive. 

cUnitAvail (ULONG) 12 
The number of free allocation units. 

cbSector (USHORT) 14 


The number of bytes that make up a sector. 


Used by: DosQueryFSInfo -152 





ilype (USHORT) 0 
The device type. 
Constant Description 

FSAT_CHARDEV 1 Resident character device. 

FSAT_PSEUDODEV 2 Pseudocharacter device. 

FSAT_LOCALDRV 3 Local drive. 

FSAT_REMOTEDRV 4 Aremote drive attached to the file system driver. 
cbName (USHORT) 2 
The length, in bytes, of the drive name, excluding the null. 
cbFSDName (USHORT) 4. 


The length, in bytes, of the file system driver name, excluding the null. 
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cbFSAData (USHORT) 6 
The length, in bytes, of the file system driver attach data returned by the file system driver. 
szName[1] (UCHAR) 8 
The null-terminated name of the device. 

szFSDName[1] (UCHAR) 9 


The null-terminated name of the file system driver the device is attached to. This is actually 
the name exported by the file system driver, which may be different than the file system dri- 
ver name found in the boot sector. This field will be null for local character devices. This 
string is actually located immediately after the null-terminated device name. 


rgFSAData[1] (UCHAR) 10 
The file system driver attach data returned by the file system driver. This field will be null for 
local character devices. This string is actually located immediately after the null-terminated 
file system driver name. 


Used by: DosQueryFSAttach -150 





Memory 


anagement 





S/2 provides memory management APIs that utilize paged virtual 

memory with 32-bit linear addressing (referred to as flat address- 
ing). These features make it very easy to handle even large blocks of 
memory (referred to as memory objects) without concern for segment 
boundaries. Segment boundaries still exist, but, they are 32-bit and pro- 
vide up to 4 gigabytes of linear address space. However, to maintain com- 
patiblity for 16-bit applications using tiled memory, processes only have 
access to the first 512 megabytes of linear address space. Of this 512 
megabytes, at least 64 megabytes is reserved for shared memory objects. 
Additional memory will be used for operating system overhead and 
space for the application itself, which leaves less than 448 megabytes of 
nonshared memory available for allocation by the application. The 
memory actually available for use varies from system to system, based on 
each system ’s available hard disk space and RAM configuration. 

Private memory is allocated from the bottom of the address range, 
and expands upward. DLL code and data and shared memory respec- 
tively are allocated from the 512 megabyte boundary, and expand 
downward. The address space between 512 megabytes and 4 gigabytes 
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is for use by the operating system. Any allocated shared memory takes 
up address space across all processes even if the other processes don’t 
have access to it. 


Memory Objects 


Memory allocation and manipulation in OS/2 is performed in terms 
of memory objects. Memory objects are allocations of one or more 
pages of memory. Since a page of memory is 4k, the minimum mem- 
ory allocation (memory object) is 4k. Memory objects are not relocat- 
able or resizeable, but they can be larger than 64k in size. To maintain 
compatibility, all OS/2 memory objects are tiled. Tiled memory ob- 
jects are allocated in the first 512 megabytes of linear address space 
and have 16-bit selectors that map to each 64k boundary of the object. 
Tiled memory objects always begin on a 64k boundary, and they always 
reserve linear address space up to the nearest 64k boundary even 
though a lesser amount was requested. Do not design applications that 
require tiled memory because this will reduce the portability of your 
application. New versions or variations of OS/2 such as Workplace OS 
may not allow tiled memory allocations. 


Memory Commitment 


Private memory is allocated using DosAllocMem, and shared memory is 
allocated using DosAllocSharedMem. But, before memory can be used 
it must be committed. By default, memory allocated with DosAllocMem 
and DosAllocSharedMem is uncommitted, which means only linear ad- 
dress space is reserved. Committed memory is backed by demand pages, 
which are physical memory pages in both RAM and the swap file that are 
initialized with zeros the first time they are touched. This is done to en- 
sure that memory is not being wasted by programs that allocate it, and 
then only use a portion of it at that time. Because the memory is not ac- 
tually there until it is touched, it is possible for the system to return a 
good return code for a memory request and then trap when the mem- 
ory is used. Memory commitment can occur at the time of allocation or 
when needed by using DosSetMem. 


Shared Memory 


Memory objects that need to be accessible by multiple processes must 
be allocated as shared memory. Shared memory objects can be named 
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or unnamed. When using named shared memory, the memory object 
must be referenced by its name by the processes that need access to it. 
Unnamed shared memory can be “giveable,” “gettable,” or both. For 
giveable memory, the owning process calls DosGiveSharedMem and 
specifies a process ID for the process that needs access to it. Client 
processes can obtain access to gettable memory by calling DosGet- 
SharedMem and passing it the base address of the unnamed shared 
memory object. When using giveable or gettable memory, the owning 
process needs to use some form of interprocess communication to let 
the client processes know the base address of the shared memory 
object. 


Memory Pools 


Although allocating memory in page increments provides good per- 
formance characteristics on Intel architecture, the 4k granularity is 
wasteful with RAM. To avoid wasting memory, OS/2 provides the ca- 
pability to specify a range of pages (using DosSubSetMem) in a mem- 
ory object asa memory pool. This pool is analogous to the C heap with 
the exception that OS/2 memory pools can be allocated in shared 
memory. Memory allocations from a memory pool can be performed 
using DosSubAllocMem which allocates memory up to the nearest 8- 
byte boundary. When using memory pools in shared memory that are 
using the serialization feature, the client processes must separately ob- 
tain access to the memory pool after obtaining access to the shared 
memory object. A client process obtains access to the shared memory 
pool by calling DosSubSetMem with the identical flags that the owning 
process used to allocate the pool, with the exception of the DOS- 
SUB_INIT flag. 


Thread-local Memory 


Since all threads have access to the same data segment of a process, it 
is sometimes valuable to be able to allocate memory that is scoped to a 
particular thread. Each thread allocating thread-local memory is given 
the same virtual address, however, each instance is backed by different 
physical memory. Thread-local memory can be allocated by calling 
DosAllocThreadLocalMemory, and freed with DosFreeThreadLocal- 
Memory. Only 8 DWORDs of thread-local memory can be allocated at 
a time, and a maximum of 32 DWORDs is available to the entire 
process. Those writing DLLs for commercial use should avoid using 
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thread-local memory, since there is no guarantee that any will be left 
for the DLL. 


Warnings and Restrictions 


@ The maximum of private memory per process is 448mb. 

The minimum available shared memory is 64mb. 

@® The minimum memory object allocation is 4k. The minimum sub- 
allocation is 8 bytes. 

@ There is no interface for determining the total amount of free mem- 
ory in the system. 

@ Memory objects cannot be relocated or resized. 

@ All memory is allocated as tiled memory regardless of whether the 

OBJ_TILED flag is used. This is to maintain compatibility with 16-bit 

applications. 

The APIs do not allow you to mark pages so that they cannot be 

swapped. 


Memory Functions 





DosAllocMem allocates a private memory object (pg. 162). 
DosFreeMem frees a private memory object or, in the case of shared 
memory, discontinues access to the shared memory object for the call- 
ing process (pg. 165). 

DosSetMem allows the changing of attributes on a range of pages in- 
cluding committing and decommitting pages (pg. 166). 
DosQueryMem queries attribute information on a range of pages ac- 
cessible by the current process (pg. 169). 





@ DosAllocMem Private Memory Management 


Allocates a private memory object for the calling process. 


SYNTAX 


APIRET DosAllocMem(PPVOID ppBaseAddress, ULONG ulOlyectSize, 
ULONG /lAllocationFlags) 
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PARAMETERS 


ppBaseAddress - output 

A pointer to a void pointer that will receive the address of the newly al- 
located object. 

ulObjectSize - input 

The size, in bytes, of the memory object. This value will be rounded up 
to the nearest 4k (1 page) boundary. 

fiAllocationFlags - input 

The following allocation flags may be chosen: 


Allocation Flags Description 
PAG_COMMIT 0x10 Commit the memory now. 
OBJ_TILE _ Ox40 The memory object requested must be tiled. 


Tiled memory is allocated in the first 512mb 
of address space, with 16-bit selectors that 
map to the object. The virtual address will 
always start on a 64k boundary. This option 
was provided for applications being ported 
from 16-bit OS/2. 


At least one of the following access flags must be chosen: 


Access Protection Flags Description 

PAG_READ Ox01 Read access is desired for the entire memory 
object. 

PAG_WRITE Ox02 Write access is desired for the entire memory 
object. 

PAG EXECUTE 0x04 Execute access is desired for the entire 


memory object. This attribute is the same as 
PAG READ on Intel 386 architecture. 


PAG_GUARD 0x08 Request that the memory object generate a 
guard page exception (XCPT_GUARD_- 
PAGE_VIOLATION) when an attempt is 
made to access the memory. 


The following helper macros may be chosen for the ulAllocationFlags pa- 
rameter: 
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Helper Macros Macro Expansion 

fPERM 0x07 (PAG_EXECUTE | PAG READ | PAG WRITE) 

fALLOC 0x57 (OBJ_TILE | PAG_COMMIT | fPERM) 

RETURNS 

0 NO_ERROR 87 ERROR INVALID _ 

PARAMETER 

8 ERROR NOT _ 95 ERROR INTERRUPT 
ENOUGH_MEMORY 

OTHER INFO 

Include file: bsedos.h, bsememf.h Define: INCL. DOSMEMMGR 

Ordinal: 299 DLL: DOSCALLS 

SEE ALSO 


DosAllocSharedMem -172, DosFreeMem -165, DosSetMem -166, 
DosSubAllocMem -180 


NOTES 


Write access implies both read and execute access. 

The guard page attribute may be used when automatic stack 
growth is desired. When this attribute is used, the first page of the 
memory object is marked as a guard page. The system will generate a 
guard page exception when an attempt is made to access a committed 
page that is marked as a guard page. The default system exception 
handler behavior is to remove the guard page attribute from the page 
and attempt to commit and mark the next page (the previous page 
since the system treats it as a stack) as a guard page. If the system can- 
not mark and commit the next page, it will generate an XCPT_UN- 
ABLE_TO_GROW_STACK exception and terminate the thread. An 
application can substitute its own exception handling with DosSet- 
ExceptionHandler. 

Unless the NOSWAP option is used for the MEMMAN statement 
in CONFIG.SYS, your pages may be swapped to disk. Currently, there 
is no way via the APIs to set a protected page that cannot be swapped. 


RESTRICTIONS/WARNINGS 


@ Unless the PAG_COMMIT flag is used, the allocated memory object 
will only have reserved linear address space. The memory must be 
committed before it can be used. 
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@ Committed pages are initially backed by demand pages. Demand 
pages are physical memory pages that exist in both RAM and the 
swapper file. The first attempt to read from or write to the page will 
cause the demand page to be truly committed and initialized with 
zeros. It is possible to successfully commit pages and then get an ac- 
cess violation when you attempt to use them since they are not truly 
committed until they are first used. Unfortunately, this is why OS/2 
can become unstable when the swap file becomes full. You can en- 
sure that your pages will exist when you commit them by setting the 
COMMIT option for the MEMMAN statement in CONFIG.SYS, 
however, this requires an enormous amount of RAM. 





@ DosFreeMem Memory Management 


Frees a private memory object or releases access to a shared memory 
object. 


SYNTAX 
APIRET DosFreeMem(PVOID pBaseAddress) 


PARAMETERS 


pBaseAddress - input 

The base address of the private memory object to be freed or, in the 
case of shared memory, the address of the shared memory object to 
discontinue access for the calling process. 


RETURNS 

0 NO_ERROR 95 ERROR INTERRUPT 

5 ERROR ACCESS DENIED 487 ERROR INVALID ADDRESS 
OTHER INFO 

Include file: bsedos.h, bsememf.h Define: INCL DOSMEMMGR 
Ordinal: 304 DLL: DOSCALLS 

SEE ALSO 


DosAllocMem -162, DosAllocSharedMem -172 


NOTES 


Freeing a named shared memory object decrements the reference 
count to the object by 1. When the reference count for the object for 
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the calling process reaches zero, the object is no longer accessible 
to the calling process, and the system-wide reference count is decre- 
mented by 1. 

Freeing an unnamed shared memory object decrements the sys- 
tem-wide reference count for the object and immediately removes ac- 
cess to the object for the calling process. 

When the reference count for a named or unnamed shared mem- 
ory object across all processes reaches zero, the memory object will 
then be freed from system memory. An attempt to access freed mem- 
ory will result in a general protection fault. 

An attempt to free an object to which the calling process does not 
have access will result in an ERROR_INVALID ADDRESS return code. 





DosSetMem Memory Management 


Sets the desired access protection and memory commitment for a 
range of pages for the calling process. 


SYNTAX 


APIRET DosSetMem(PVOID pBaseAddress, ULONG ulRegionSize, 
ULONG wlPageAtinbutes) 


PARAMETERS 


pBaseAddress - input 

The base address of the first page of a range of pages whose attributes 
will be set. 

ulRegionSize - input 

The size, in bytes, of the range of pages whose attributes will be set. If 
the size specified does not end on a page boundary, the size will be 
rounded up to the nearest page boundary. 

fiAllocationFlags - input 

The allocation flags to be set for the range of pages. The following 
flags are valid: 


Commit Flags Description 


PAG_COMMIT 0x10 Commit the range of pages. The pages are to be 
backed by demand pages. 


PAG_DECOMMIT 0x20 Decommit the range of pages. The pages will 
lose their backing storage. Shared memory 
pages cannot be decommitted. 
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If no commit flags are specified, then no change in commitment 
will be made. 


Access Protection Flags Description 
PAG_READ Ox01 Read access is desired for the pages. 
PAG_WRITE 0x02 Write access is desired for the pages. 


PAG_EXECUTE 0x04 Execute access is desired for the pages. This 
attribute is the same as PAG_READ on Intel 386 
architecture. 


PAG_GUARD 0x08 Mark the pages as guard pages. This will cause 
the memory object to generate a guard page 
exception (XCPT_GUARD_PAGE_VIO- 
LATION) when an attempt is made to access 
the memory. 


PAG_DEFAULT — 0x400 Set the access protection to what the calling 
process requested when it allocated the 
memory. 


If the PAG_DECOMMIT flag is not set, then either the PAG_ 
DEFAULT, PAG_READ, PAG_WRITE, or PAG_EXECUTE flag must be 
specified. 

Access protection can only be assigned to committed pages. 


RETURNS 
0 NO_ERROR 95 ERROR INTERRUPT 
5 ERROR ACCESS _ 212 ERROR LOCKED 
DENIED 
8 ERROR NOT_ 487 ERROR INVALID ACCESS 
ENOUGH_MEMORY 
87 ERROR_INVALID _ 32798 ERROR CROSSES _ 
PARAMETER OBJECT_BOUNDARY 
OTHER INFO 
Include file: bsedos.h, bsememf.h Define: INCL _DOSMEMMGR 
Ordinal: 305 DLL: DOSCALLS 
SEE ALSO 


DosAllocMem -162, DosAllocSharedMem -172, DosQueryMem -169 
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NOTES 


This function can change the commit option and access protection on 
both private and shared memory objects. 

The guard page attribute may be used when automatic stack 
growth is desired. When this attribute is used, the first page of the 
memory object is marked as a guard page. The system will generate a 
guard page exception when an attempt is made to access a committed 
page that is marked as a guard page. The default system exception 
handler behavior is to remove the guard page attribute from the page 
and attempt to commit and mark the next page (the previous page 
since the system treats it as a stack) as a guard page. If the system can- 
not mark and commit the next page, it will generate an XCPT_UN- 
ABLE_TO_GROW_STACK exception and terminate the thread. An 
application can substitute its own exception handling with DosSet- 
ExceptionHandler. 

On the Intel 386, 486, and Pentium processors, execute and read 
access are equivalent, and write access implies both read and execute 
access. 


RESTRICTIONS/WARNINGS 


@ With regard to shared memory, if a client process (that is, any 
process other than the creator of the memory object) attempts to 
set access rights that are greater than the access rights of the process 
that created the shared memory, then ERROR_ACCESS_DENIED is 
returned. 

@ Access protection changes only work on pages that are committed. 
Noncommitted pages have an access of “no access.” 

This call may not be used on free pages; that is, pages that have 
not been allocated using DosAllocMem or DosSharedAllocMem are 
called free pages. Pages can be committed and decommitted only 
for nonfree pages. 

@® Committing pages in shared memory objects affects all processes 
with access to the memory object, not just the process that commit- 
ted the pages. Access protection changes only apply to the calling 
process. 

@® Committed pages are initially backed by demand pages. Demand 
pages are physical memory pages that exist in both RAM and the 
swapper file. The first attempt to read from or write to the page will 
cause the demand page to be truly committed and initialized with 
zeros. It is possible to successfully commit pages and then get an ac- 
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cess violation when you attempt to use them since they are not truly 
committed untill they are first used. Unfortunately, this is why OS/2 
becomes very unstable when the swap file becomes full. You can en- 
sure that your pages will exist when you commit them by setting the 
COMMIT option for the MEMMAN statement in CONFIG.SYS. 

@® Committed pages in shared memory objects cannot be decom- 
mitted. 

@ Decommitted pages lose their backing storage and are inaccessible. 

A decommitted page may be recommitted at any time there is 

enough backing storage available. 

This call replaces the current access protection on the specified 

page range with the newly specified attributes. 

If the call fails on any page that it is processing, it will stop process- 

ing and return an error. No changes will take effect. 





DosQueryMem Memory Management 


Queries the attribute information on a range of pages allocated for the 
current process. 


SYNTAX 


APIRET DosQueryMem(PVOID pBaseAddress, PULONG pulRegion- 
Size, PULONG /lAllocationFlags) 


PARAMETERS 


pBaseAddress - input 

The base address of the first page of a range of pages to be queried. 
The base address cannot be less than 0x10000 (64k) and not greater 
than 0x20000000 (512 meg). 

pulRegionSize - input/output 

On input, the address of a ULONG that contains the size, in bytes, of 
the range of pages to be queried. If the size specified does not end on 
a page boundary, the query will be rounded up to the nearest page 
boundary. On output, this value contains the actual size, in bytes, of 
the range of pages to be queried (because of rounding). 
fiAllocationFlags - output 

A pointer to a ULONG that will receive the allocation flags that were 
specified for the range of pages. The following flags are valid: 
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Allocation Flags Description 


PAG COMMIT Oxl0 The pages are committed; that is, they are 
backed by demand pages. 


PAG_FREE 0x4000 The pages are free and have no backing storage. 


PAG_SHARED = _0x2000 The pages specified are part of a shared 
memory object. If not set, the pages belong to a 
private memory object. 


PAG_BASE 0x10000 ‘The first page specified in pBaseAddress is the 
first page of an allocated memory object. 


Access Protection Flags Description 

PAG_READ OxO1 Read access is set for the committed range of 
pages. 

PAG_WRITE 0x02 Write access is set for the committed range of 
pages. 

PAG_EXECUTE 0x04 Execute access is set for the committed range of 
pages. 

PAG_GUARD 0x08 The committed range of pages are marked as 


guard pages and will generate a guard page 
exception if touched. 


RETURNS 


0 NO_ERROR 487 ERROR_INVALID_ADDRESS 
87 ERROR_INVALID_ 32794 ERROR_NO_OBJECT 
PARAMETER 
95 ERROR_INTERRUPT 


OTHER INFO 


Include file: bsedos.h, bsememf.h Define: INCL_DOSMEMMGR 
Ordinal: 306 DLL: DOSCALLS 


SEE ALSO 
DosAllocMem -162, DosAllocSharedMem -172, DosSetMem -166 


NOTES 


The page attributes are determined for the first page, and then the 
rest of the pages are scanned sequentially until the first page with a 
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nonmatching set of attributes is encountered or a page that belongs to 
a different memory object is encountered. If the search stops for one 
of the aforementioned reasons, then the pulRegionSize parameter will 
contain the total bytes scanned before the stop occurred. If informa- 
tion is still needed for the rest of the pages originally requested to be 
queried, a new base starting address and region size can be calculated 
by 6 programs using the following formulas: 


pNewBase = (PBYTE)pOldBase + *pulRegionSize(on output) + 1; 
*pulNewRegionSize = *pulRegionSize(on input) - *pulRegionSize(on 
output) - 1; 


You can determine the memory map for the calling process by re- 
peatedly calling DosQueryMem. If the scan stops prematurely, check 
the first page following the stop to see if it has the PAG_BASE flag set. 
If so, you know you have entered the next memory object; if not, then 
only the allocation flags changed. 

A page that has not yet been committed, or has been decommitted 
without being freed, has an access of “no access.” No access is indicated 
by having neither the PAG_COMMIT flag nor PAG_FREE flag set. 

The valid scanning range is from 0x10000 through 0x2000000. An 
attempt to scan outside of that range or to scan addresses that have not 
been reserved will cause ERROR INVALID ACCESS to be returned. 

On the Intel 386, 486, and Pentium processors, execute and read 
access are equivalent, and write access implies both read and execute 
access. 


RESTRICTIONS/WARNINGS 


@ This function operates from the perspective of the calling process; 
therefore, if you are querying memory pages in a shared memory 
object, you must first obtain access to it to get the correct results. 
Also, the access protection information only indicates what access 
protection the calling process has. 

@ Address ranges that are allocated by the system for an application’s 
code and data segments may not end on page boundaries as they 
will for memory allocated with DosAllocMem or DosAlloc- 
SharedMem. 

@ Address ranges that have not been reserved via the system, Dos- 
AllocMem, or DosAllocSharedMem will return ERROR INVALID _ 
ADDRESS. 
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Shared Memory Functions 





DosAllocSharedMem allocates a shared memory object (pg. 172). 
DosGetNamedSharedMem obtains access for the calling process to a 
previously allocated named shared memory object via its name (pg. 175). 
DosGetSharedMem obtains access for the calling process to a shared 
memory object via its base address (pg. 177). 

DosGiveSharedMem gives the target process access to a previously al- 
located shared memory object via its base address (pg. 178). 





@ DosAllocSharedMem Shared Memory Management 


Allocates a memory object that can be shared among multiple pro- 
cesses. 


SYNTAX 


APIRET DosAllocSharedMem(PPVOID ppBaseAddress, PSZ pszName, 
ULONG wlOdjectSize, VLONG 
‘[ltAllocationF lags) 


PARAMETERS 


ppBaseAddress - output 

A pointer to a void pointer that will receive the address of the newly al- 
located object. 

pszName - input 

A null-terminated string containing the name of the shared memory 
object. The name must have the format of an OS/2 file name and must 
begin with the prefix \SSHAREMEM\ If NULL is used for this parame- 
ter, then the memory is considered unnamed shared memory. 
ulObjectSize - input 

The size, in bytes, of the shared memory object. This value will be 
rounded up to the nearest 4k (1 page) boundary. 

fiAllocationFlags - input 

The following allocation flags may be chosen: 
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Allocation Flags Description 


PAG_COMMIT 0x10 The memory requested is to be initially 
committed. 


OBJ_TILE 0x40 The memory object requested must be tiled. 
Tiled memory is allocated in the first 512mb of 
address space, with 16-bit selectors that map to 
the object. The virtual address will always start 
on a 64k boundary. This option was provided for 
applications being ported from 16-bit OS/2. 


OBJ_GETTABLE 0x100 Another process that knows the address of the 
shared memory may gain access to it by calling 
DosGetSharedMem. 


OBJ_GIVEABLE  0x200 Access to the shared memory can be given to 
another process by calling DosGiveSharedMem. 


At least one of the following access flags must be chosen: 


Access Protection Flags Description 

PAG_READ Ox01 Read access is desired for the entire memory 
object. 

PAG_WRITE 0x02 Write access is desired for the entire memory 
object. 


PAG _ EXECUTE 0x04 Execute access is desired for the committed 
pages in the memory object. This attribute is the 
same as PAG READ on Intel 386 architecture. 


PAG_GUARD 0x08 Request that the memory object generate a 
guard page exception (XCPT_GUARD_PAGE - 
VIOLATION) when an attempt is made to 
access the memory. 


The following helper macros may be chosen for the ulAllocationFlags 
parameter: 
Helper Macros Macro Expansion 
fPERM 0x07 (PAG_EXECUTE | PAG_READ | PAG_WRITE) 
fALLOC 0x57 (OBJ_TILE | PAG_COMMIT | fPERM) 
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fSHARE 0x300 (OBJ _GETTABLE | OBJ_GIVEABLE) 
fALLOCSHR 0x357 (OBJ_TILE | PAG_COMMIT | fSHARE | fPERM) 
RETURNS 
0 NO_ERROR 95 ERROR INTERRUPT 
8 ERROR NOT _ 123, ERROR _ INVALID NAME 
ENOUGH_MEMORY 
87 ERROR INVALID _ 183. ERROR ALREADY EXISTS 
PARAMETER 
OTHER INFO 
Include file: bsedos.h, bsememf.h Define: INCL._DOSMEMMGR 
Ordinal: 299 DLL: DOSCALLS 
SEE ALSO 


DosAllocMem -162, DosFreeMem -165, DosGetNamedSharedMem -175, 
DosGetSharedMem -177, DosGiveSharedMem -178, DosSetMem -166, 
DosSubAllocMem -180 


NOTES 


Shared memory objects have the same virtual address in each process 
from which they are accessed. 

On the Intel 386, 486, and Pentium processors, execute and read 
access are equivalent, and write access implies both read and execute 
aCCeSS. 

The guard page attribute may be used when automatic stack growth 
is desired. When this attribute is used, the first page of the memory ob- 
ject is marked as a guard page. The system will generate a guard page 
exception when an attempt is made to access a committed page that is 
marked as a guard page. The default system exception handler behav- 
ior is to remove the guard page attribute from the page and attempt to 
commit and mark the next page (the previous page since the system 
treats it as a stack) as a guard page. If the system cannot mark and com- 
mit the next page, it will generate an XCPT_UNABLE_TO_GROW_ 
STACK exception and terminate the thread. An application can sub- 
stitute its own exception handling with DosSetException Handler. 

Unless the NOSWAP option is used for the MEMMAN statement 
in CONFIG.SYS, your pages may be swapped, however, this requires a 
large amount of RAM. Currently, there is no way via the APIs to set a 
protected page that cannot be swapped. 
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RESTRICTIONS/WARNINGS 


@ Named shared memory objects must be requested by name. If an at- 
tempt is made to “give” or “get” named shared memory, an error will 
be returned. 

@ Unless the PAG_COMMIT flag is used, the allocated memory object 
will only have reserved linear address space. The memory must be 
committed before it can be used. 

® Committed pages are initially backed by demand pages. Demand 
pages are physical memory pages that exist in both RAM and the 
swapper file. The first attempt to read from or write to the page will 
cause the demand page to be truly committed and initialized with ze- 
ros. It is possible to successfully commit pages and then get an access 
violation when you attempt to use them since they are not truly com- 
mitted until they are first used. Unfortunately, this is why OS/2 may 
become unstable when the swap file becomes full. You can ensure 
that your pages will exist when you commit them by setting the COM- 
MIT option for the MEMMAN statement in CONFIG.SYS, however, 
this requires a large amount of RAM. This option will cause swapper 
space to be reserved each time memory is committed. 





DosGetNamedSharedMem Shared Memory Management 


Obtains access to the named shared memory object for the calling 
process. 


SYNTAX 


APIRET DosGetNamedSharedMem(PPVOID ppBaseAddress, PSZ 
pszSharedMemName, VLONG 
[Access lags) 


PARAMETERS 


ppBaseAddress - output 

A pointer to a pointer that is to receive the base address of the shared 
memory object. 

pszSharedMemName - input 

A pointer to a null-terminated string containing the name of the 
shared memory object. 

fAccessFlags - input 

Specify the following flags for the desired access protection: 
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Access Protection Flags Description 

PAG_READ OxO01 Read access is desired for the entire memory 
object. 

PAG_WRITE Qx02 Write access is desired for the entire memory 


object. Write access implies execute access. 


PAG EXECUTE 0x04 Execute access is desired for the committed 
pages in the memory object. This attribute is the 
same as PAG READ on Intel 386 architecture. 


PAG_GUARD 0x08 Request that the memory object generate a 
guard page exception (XCPT_GUARD_ 
PAGE_VIOLATION) when an attempt is made 
to access the memory. 


At least one of the PAG READ, PAG WRITE, or PAG EXECUTE 
flags must be specified. The flags specified for this parameter must be 
compatible with the flags that were used when the shared memory ob- 
ject was allocated. 


RETURNS 


0 NO_ERROR 95 ERROR_INTERRUPT 
2 ERROR_FILE_NOT_FOUND 123 ERROR_INVALID_NAME 
8 ERROR_NOT_ENOUGH_ 212 ERROR LOCKED 
MEMORY 
31 ERROR_GEN_FAILURE 


OTHER INFO 

Include file: bsedos.h, bsememf.h Define: INCL_DOSMEMMGR 
Ordinal: 301 DLL: DOSCALLS 

SEE ALSO 


DosAllocSharedMem -172, DosGetSharedMem -177, 
DosGiveSharedMem -178 


NOTES 


Each call to DosGetNamedSharedMem increments the reference 
count for the memory object for the calling process by one. If the ref- 
erence count for the calling process were to exceed 65535, ER- 
ROR _GEN_ FAILURE is returned and the reference count remains 
65535. 
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On the Intel 386, 486, and Pentium processors, execute and read 
access are equivalent, and write access implies both read and execute 
access. 


RESTRICTIONS/WARNINGS 


@ A client process (the process requesting access to the shared memory 
object) cannot request greater access to the shared memory object 
than was requested by the process that created the object, otherwise 
ERROR ACCESS DENIED is returned. 





DosGetSharedMem Shared Memory Management 


Obtains access to a shared memory object via the object’s virtual ad- 
dress. 


SYNTAX 

APIRET DosGetSharedMem(PVOID pBaseAddress, ULONG 
‘flAccessF lags) 

PARAMETERS 


pBaseAddress - input 

The base address of the gettable shared memory object you wish to ob- 
tain access to. This object must have been allocated using DosAlloc- 
SharedMem with the OBJ_GETTABLE flag. 

flAccessFlags - input 

Specify the following flags for the desired access protection: 


Access Protection Flags Description 

PAG_READ Ox01 Read access is desired for the entire memory 
object. 

PAG_WRITE 0x02 Write access is desired for the entire memory 


object. Write access implies execute access. 


PAG EXECUTE 0x04 Execute access is desired for the committed 
pages in the memory object. This attribute is the 
same as PAG_ READ on Intel 386 architecture. 


PAG_GUARD 0x08 Request that the memory object generate a 
guard page exception (XCPT_GUARD_PAGE - 
VIOLATION) when an attempt is made to 
access the memory. 
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At least one of the PAG_READ, PAG WRITE, or PAG_ EXECUTE 
flags must be specified. The flags specified for this parameter must be 
compatible with the flags that were used when the shared memory ob- 
ject was allocated. 


RETURNS 


0 NO_ERROR 95 ERROR INTERRUPT 

5 ERROR ACCESS_DENIED 212 ERROR LOCKED 

8 ERROR _NOT_ENOUGH_ 487 ERROR_INVALID ADDRESS 
MEMORY 

87 ERROR_INVALID_PARAMETER 


OTHER INFO 

Include file: bsedos.h, bsememf.h Define: INGL_DOSMEMMGR 
Ordinal: 302 DLL: DOSCALLS 

SEE ALSO 


DosAllocSharedMem -172, DosGetNamedSharedMem -175, 
DosGiveSharedMem -178 


NOTES 


Each process that wants access to a shared memory block allocated in 
another process must request it before using it. When using the 
DosGetSharedMem, the process that allocated it must somehow com- 
municate the base pointer of the shared memory object to the process 
that desires access. This is traditionally done using some form of inter- 
process communication (IPC) like pipes, queues, or PM messages. 

Each call to DosGetSharedMem increments the system-wide refer- 
ence count for the memory object by one. 


RESTRICTIONS/WARNINGS 


@ ERROR_ACCESS_DENIED will be returned if the shared memory 
object was not allocated with the OBJ_GETTABLE flag. 

@ A client process (the process requesting access to the shared memory 
object) cannot request greater access to the shared memory object 


than was requested by the process that created the object, otherwise 
ERROR ACCESS DENIED is returned. 





DosGiveSharedMem Shared Memory Management 


Grants access to a shared memory object to another process. 
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SYNTAX 

APIRET DosGiveSharedMem(PVOID pBaseAddress, PID ProcessID, 
ULONG /lAccessFlags) 

PARAMETERS 


pBaseAddress - input 

The base address of the shared memory object whose access will be 
granted to another process. 

ProcessID - input 

The ID of the target process that will receive access to the shared mem- 
ory object. 

flAccessFlags - input 

Specify the following flags for the desired access protection: 


Access Protection Flags Description 

PAG_READ Ox01 Read access is desired for the entire memory 
object. 

PAG_WRITE 0x02 Write access is desired for the entire memory 


object. Write access implies execute access. 


PAG EXECUTE 0x04 Execute access is desired for the committed 
pages in the memory object. This attribute is the 
same as PAG READ on Intel 386 architecture. 


PAG_GUARD 0x08 Request that the memory object generate a 
guard page exception (XCPT_GUARD_PAGE. - 
VIOLATION) when an attempt is made to 
access the memory. 


At least one of the PAG READ, PAG WRITE, or PAG _ EXECUTE 
flags must be specified. The flags specified for this parameter must be 
compatible with the flags that were used when the shared memory ob- 
ject was allocated. 


RETURNS 


0 NO_ERROR 95 ERROR_INTERRUPT 

5 ERROR_ACCESS DENIED 212 ERROR _LOCKED 

8 ERROR_NOT_ENOUGH_ = 303: ERROR_INVALID_PROCID 
MEMORY 

87 ERROR_INVALID_ 487 ERROR_INVALID_ADDRESS 
PARAMETER 
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OTHER INFO 

Include file: bsedos.h, bsememf.h Define: INCL_DOSMEMMGR 
Ordinal: 303 DLL: DOSCALLS 

SEE ALSO 


DosAllocSharedMem -172, DosGetNamedSharedMem -175, 
DosGetSharedMem -177, WinQueryWindowProcess 


NOTES 


While this function will give access to a shared memory object to an- 
other process, it won't give that process the base address of the object. 
Therefore, some form of IPC like pipes, queues, or PM messages must 
be used to pass this value to the target process. 

Each call to DosGiveSharedMem increments the system-wide ref- 
erence count for the memory object by one. 

Shared memory objects have the same virtual address in each 
process that has access to it. 


Memory Suballocation (Heap Management) Functions 


DosSubAllocMem suballocates a block of memory from a heap that 
was initialized with DosSubSetMem (pg. 180). 

DosSubFreeMem releases a suballocated block of memory back to the 
heap (pg. 182). 

DosSubSetMem initializes a portion of a memory object as a heap for 
suballocation. This function can also increase the size of a previously 
allocated heap (pg. 183). 

DosSubUnsetMem deletes a heap created with DosSubSetMem (pg. 





185). ; 
@ DosSubAllocMem Heap Management 


Allocates a block of memory from a pool of memory that exists in a pri- 
vate or shared memory object. 


SYNTAX 


APIRET DosSubAllocMem(PVOID pHeapOffset, PPVOID ppBlock- 
Offset, ULONG wilBlockSize) 
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PARAMETERS 


pHeap Offset - input 

An offset to a heap that was created with DosSubSetMem. The memory 
will be allocated from this heap. 

ppBlockOffset - output 

The address of a PVOID that will receive a pointer to the allocated 
memory block. 

ulBlockSize - input 

The size, in bytes, of the requested memory block. This value will be 
rounded up to the nearest 8-byte boundary if the size specified is not a 
multiple of 8. 


RETURNS 

0 NO_ERROR 311 ERROR DOSSUB_NOMEM 
87 ERROR INVALID _ 532 ERROR DOSSUB_ 

PARAMETER CORRUPTED 

OTHER INFO 
Include file: bsedos.h, bsememf.h Define: INCL. DOSMEMMGR 
Ordinal: 345 DLL: DOSCALLS 
SEE ALSO 


DosSubFreeMem -182, DosSubSetMem -183, DosSubUnsetMem -185, 
malloc, calloc 


NOTES 


The maximum value of ulBlockSize is the size of the heap created with 
DosSubSetMem, minus 64 bytes. 

If the area used to manage the suballocation functions (the first 
64 bytes of the heap) has been corrupted, then ERROR_DOSSUB_ 
CORRUPTED is returned. 

If there is not enough memory in the heap to honor the request, 
then ERROR DOSSUB_NOMEM is returned. 


RESTRICTIONS/WARNINGS 


@ You must keep track of the size of the allocated block and the base 
address of the heap it was allocated from, because these values are 
required for DosSubFreeMem. 

@ Before a process other than the owner process can allocate from the 
heap it must first call DosSubSetMem with the identical flags that 
were used to create the heap, except for the DOSSUB_INIT flag. An 
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attempt to allocate memory from a heap that the requesting process 
does not have access to will result in an ERROR_DOSSUB_COR- 
RUPT return code. 





@ DosSubFreeMem Heap Management 


Frees a suballocated block of memory back to the heap. 


SYNTAX 


APIRET DosSubFreeMem(PVOID pHeapOffset, PVOID pBlockOffset, 
ULONG wlBlockSize) 


PARAMETERS 


pHeap Offset - input 

The address of the base of the heap that was created using DosSub- 
SetMem. 

pBlockOffset - input 

The address of the suballocated block that is to be freed. 

ulBlockSize - input 

The size, in bytes, of the suballocated block. If this value is not a multi- 
ple of 8 bytes, it will be rounded up to the nearest 8-byte boundary. 


RETURNS 

0 NO_ERROR 312 ERROR DOSSUB_OVERLAP 
87 ERROR _ INVALID _ 532 ERROR DOSSUB_ 

PARAMETER CORRUPTED 

OTHER INFO 
Include file: bsedos.h, bsememf.h Define: INCL_DOSMEMMGR 
Ordinal: 346 DLL: DOSCALLS 
SEE ALSO 


DosSubAllocMem -180, DosSubSetMem -183, DosSubUnsetMem -185 


NOTES 

If the area used to manage the suballocation functions (the first 64 
bytes of the heap) has been corrupted, then ERROR_DOSSUB_COR- 
RUPTED is returned. 
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If the amount of memory to be freed would overlap another sub- 
allocated block, then ERROR DOSSUB_OVERLAP is retuned. This 
return code can also occur if the same block is freed more than once. 





DosSubSetMem Heap Management 


Sets up a heap within a private or shared memory object, or increases 
the size of a previously allocated heap. 


SYNTAX 


APIRET DosSubSetMem(PVOID pSitartOfHeap, ULONG ulFlags, 
ULONG uilSzze) 


PARAMETERS 

pStartOfHeap - input 

The address of the first page that the heap starts from. 

ulFlags - input 

OR together the following flags for the desired characteristics of the 
heap: 


Flags Description 


DOSSUB_INIT QOx01 Initialize the specified area of the memory 
object as a heap to be used for suballocation. 
If this flag is not specified and the request is 
issued against a heap in a shared memory 
object that was allocated by another process 
using DosSubSetMem, then the requesting 
process will be granted access (or attached) 
to the heap (see Restrictions/ Warnings). It 
is only necessary to attach to heaps that are 
created with the DOSSUB_SERIALIZE flag. 


DOSSUB_GROW QOx02 ‘The request is to increase the size of the 
heap to the number of bytes specified in 
ulSize. 


DOSSUB_SPARSE_OBJ 0x04 The request is to have the system manage 
the requested heap. The system will 
dynamically commit pages as they are 
needed. The pages that span the length of 
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the heap should be left uncommitted. If this 
flag is not specified, DosSubAllocMem will 
assume that all pages that span the heap are 
already committed. 


DOSSUB_SERIALIZE 0x08 The request is to have the system serialize 
access to the heap. The system will only 
serialize DosSubAllocMem and 
DosSubFreeMem. 


ulSize - input 


The size of the heap, in bytes. If the size specified is not a multiple of 
8, it will be rounded down to the nearest multiple of 8. 


RETURNS 


QO NO_ERROR 310 ERROR _DOSSUB_SHRINK 
87 ERROR_INVALID_PARAMETER 


OTHER INFO 


Include file: bsedos.h, bsememf.h Define: INCL_DOSMEMMGR 
Ordinal: 344 DLL: DOSCALLS 


SEE ALSO 


DosSubAllocMem -180, DosSubFreeMem -182, 
DosSubUnsetMem -185 


NOTES 


DosSubUnsetMem must be called to free the resources allocated to 
manage the suballocation function when the heap is no longer 
needed. 

The suballocation function requires 64 bytes of space from the 
heap area for control information. Therefore, the minimum size of 
the heap is 72 bytes. 

If the request is to grow the heap and the value for u/lSvzze is less 
than the current size, then ERROR DOSSUB_SHRINK is returned. 
Heaps cannot be shrunk. 

Even though you may only wish to grow the heap, you must still 
specify all of the original allocation flags, otherwise ERROR_IN- 
VALID PARAMETER is returned. 

If there is a request to grow the heap larger than the memory ob- 
ject that contains it, ERROR_INVALID_PARAMETER is returned. 
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RESTRICTIONS/WARNINGS 


@ Before a process other than the owner process can allocate from a 
heap that was created with the DOSSUB_SERIALIZE flag specified, 
it must issue this call with the identical flags that were used to create 
the heap except for the DOSSUB_INIT flag. This obtains access for 
the calling processs. An attempt to allocate memory from a shared 
heap (the serialize option was used) to which the requesting process 
does not have access will result in an ERROR _DOSSUB_CORRUPT 
return code. 

@ A memory object must be allocated first before DosSubSetMem is 
used. 

@ For shared memory objects, the calling process must first gain ac- 

cess to the memory object before using DosSubSetMem to attach to 

the heap. See DosGetNamedSharedMem (pg. 175), DosGetShared- 

Mem (pg. 177), and DosGiveSharedMem (pg. 178) for more infor- 

mation. 

The caller should not change the attributes or commit flags for a 

heap that is being managed by the system (see DOSSUB_SPARSE __ 

OBJ on 7-46). Also, all pages spanned by the heap must have the 

same allocation attributes. 





DosSubUnsetMem Heap Management 


Terminates use of a heap allocated using DosSubSetMem. 


SYNTAX 
APIRET DosSubUnsetMem(PVOID pHeapOffset) 


PARAMETERS 


pHeapOffset - input 
The base address of the heap to be freed. 


RETURNS 

0 NO_ERROR 532 ERROR _DOSSUB_CORRUPTED 
OTHER INFO 

Include file: bsedos.h, bsememf.h Define: INCL_DOSMEMMGR 
Ordinal: 347 DLL: DOSCALLS 

SEE ALSO 


DosSubSetMem -183 
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NOTES 


This call frees the resources allocated to manage the suballocation 
function. This function should be called before freeing the memory 
object. 

If the system-managed area of the heap is corrupted, then ER- 
ROR_DOSSUB_CORRUPTED is returned and the heap is not freed. 


Thread-local Memory Functions 





DosAllocThreadLocalMemory allocates a block of memory unique to 
each thread (pg. 186). 
DosFreeThreadLocalMemory frees a block of thread-local memory 





(pg. 187). 
DosAllocThreadLocalMemory Memory Management 


Allocates a block of memory that is thread scoped. 


SYNTAX 


APIRET DosAllocThreadLocalMemory (ULONG chNumDWords, 
PULONG *ppulThreadMem) 


PARAMETERS 


cbNumD Words - input 

The number of doublewords to allocate, up to a maximum of 8. 
*ppulThreadMem - output 

The address of a PVOID that will contain the address of the thread-lo- 
cal memory block. 


RETURNS 

0 NO_ERROR 87 ERROR INVALID PARAMETER 
8 ERROR NOT _ENOUGH_MEMORY 

OTHER INFO 

Inlude file: bsedos.h Define: INCL_DOSPROCESS 


Ordinal 454 DLL: DOSCALLS 
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SEE ALSO 
DosFreeThreadLocalMemory - 187 


NOTES 


When a process is started, a block of memory is allocated to be used as 
thread-local memory. This memory has the same virtual address for 
each thread, but is backed by separate physical memory. 


WARNINGS/RESTRICTIONS 


@ A maximum of 32 doublewords (128 bytes) is available for the entire 
process, allocatable in blocks of up to 8 doublewords (32 bytes). 

@ Care should be taken when writing DLLs for commercial use that 
use thread-local memory since there is no guarantee that any dou- 
blewords will be available to threads started by the DLL. 





DosFreeT hreadLocalMemory Memory Management 


Frees a block of thread-local memory. 


SYNTAX 
APIRET DosFreeThreadLocalMemory (PULONG pulThreadMem) 


PARAMETERS 


pulThreadMem - input 
The address of a block of thread-local memory, previously allocated 
with DosAllocThreadLocalMemory. 


RETURNS 

0 NO_ERROR 87 ERROR INVALID PARAMETER 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSPROCESS 
Ordinal 455 DLL: DOSCALLS 

SEE ALSO 


DosAllocThreadLocalMemory -186 


NOTES 


None 





Message 
Management 
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S/2 provides several APIs for using messages in message files. 

Typically, message files are used to contain strings (or messages) 
that will be displayed to the user or saved to a file at various points of 
program execution. Each message has an associated message ID and 
type. Message files typically consist of strings such as error messages, 
warning messages, help messages, informational messages, and 
prompts. The advantage of storing such strings in message files is that 
these strings can be translated into other languages without requiring 
the program to be recompiled. 

A unique message file should be maintained for each language 
supported by the program. The MKMSGF utility that comes with the 
toolkit is then used to store the associated code page and convert the 
strings to binary form. The input file to MKMSGF is a .TXT file, and 
the output file is an .MSG file. 

Optionally, message files can be bound to an executable or DLL 
using the MSGBIND utility that comes with the toolkit. Bound message 
files will load faster, but they will add size to the executable. By default, 
the message segment is packed together with application code. If the 
combined messages and code exceed 64k, then a special message seg- 
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ment must be created to handle the messages separately. The following 
statement should be added to the module definitions file (.DEF) of 32- 
bit executables to separate the messages from the application code: 


SEGMENT *_MSGSEG32’ CLASS *“CODE’ LOADONCAL 


Loading and Displaying Messages 


DosGetMessage is used to load messages from a message file or mes- 
sage segment and performs the appropriate string substitution into 
the message body. When multiple message files are linked, using the 
control file feature of MKMSGF (to support multiple languages), 
DosGetMessage will scan the message files for the version of the mes- 
sage that matches the current code page. If the code page cannot be 
found in the message files, it will use the first code page it scanned that 
contains the requested message. 

DosLoadMessage performs string substitution for messages al- 
ready in memory. This function can be used with any string in memory 
containing the correct variable substitution characters. DosPut- 
Message is used to take the message loaded with DosGetMessage and 
write it to a file or device (such as the screen). DosPutMessage cannot 
be used to write messages to the screen of Presentation Manager pro- 
grams. 

DosQueryMessageCP can be used to retrieve the list of code pages 
and language identifiers used in the specified message file or exe- 
cutable. 


Message Management Functions 





DosGetMessage loads a message from a message segment or message 
file into memory and performs the requested string substitution into 
the message (pg. 190). 

DosInsertMessage performs string substitution on a message already 
in memory (pg. 193). 

DosPutMessage writes a message to a file or device (pg. 195). 
DosQueryMessageCP retrieves the list of code pages and language 
identifiers used in the specified message file or message segments 


(pg. 196). 
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@ DosGetMessage Message Management 


Loads a message from a message file or message segment and per- 
forms the appropriate variable substitution. 


SYNTAX 


APIRET DosGetMessage (PPCHAR ppchTable, ULONG ulVarCount, 
PCHAR pchOuiMessage, ULONG ulOutMessage- 
Len, ULONG ulMessageNum, PSZ pszMsg- 
Filename, PULONG pulActualLen) 


PARAMETERS 


ppchTable - input 

A buffer containing an array of up to nine pointers to null-terminated 
SBCS or DBCS character strings. This value can be NULL if no substi- 
tution should be performed. 

ulVarCount - input 

The number of variable substitutions to be made. This number should 
match the number of strings in ppchTable. If there are no substitutions 
to be made, this should be zero. 

pchOutMessage - output 

The address of a buffer to receive the resulting message after variable 
substitution is performed in the message body. 

ulOutMessageLen - input 

The length, in bytes, of the buffer pointed to by pchOutMessage. If the 
length of the buffer is too small to receive the entire message string, 
then as much of the message that will fit is placed into the buffer and 
ERROR _ MR MSG _ TOO_LONG is returned. 

ulMessageNum - input 

The message ID to retrieve from pszMsgfilename. 

pszMsgFilename - input 

The message file to load the message from. Regardless of whether a 
path is specified, the executable is searched for a bound message first. 
If the message was not found and a path was specified, then it is 
searched, otherwise, the root directory is searched, followed by the 
current directory, the DPATH, and finally the directories listed in the 
DOS APPEND statement. 

pulActualLen - output 

The actual length of the message after variable substitution has been 
performed. 
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RETURNS 
0 NO_ERROR 318 ERROR MR UN_ 
ACC_MSGF 
2 ERROR FILE NOT_ 319 ERROR MR _INV_MSGEF _ 
FOUND FORMAT 
206 ERROR_FILENAME EXCED_ 320 ERROR MR INV_ 
RANGE IVCOUNT 
316 ERROR MR MSG _TOO_ 321 ERROR MR _UN_ 
LONG PERFORM 
317 ERROR MR MID NOT FOUND 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSMISC 
Ordinal: 6 DLL: MSG 
SEE ALSO 


DosInsertMessage -193, DosPutMessage -195, 
DosQueryMessageCP -196 


NOTES 


DosGetMessage loads the requested message from the specified mes- 
sage file (or message segment) and substitutes the strings specified in 
ppchTable into the message body. If the message text is as follows: 


XYZOZ1LSE: File @1 not £Eound on machine 32. 


and the substitution strings are ABC.DAT pointed to by index 0 in 
ppchTable, and SERVER is pointed to by index | in ppchTable, then the 
resulting string is returned: 


XYZ0218: File ABC.DAT not found on machine SERVER1. 


If ulVarCount is greater than 9, then no message text is retrieved 
and ERROR_INV_IVCOUNT is returned. 

The text substitutions will be performed by matching the number 
value of the substitution symbol with index of the string in popchTable. If 
a substitution symbol with a numeric value higher than the ulVarCount 
is found, it is ignored and the substitution symbol will be left un- 
changed in the message. If the same substitution symbol appears more 
than once in the string, the substitution will occur for each occurrence 
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of that same symbol. Substitution symbols do not have to appear in the 
message text in any particular order. 

Substitution symbols do not have to be surrounded by blanks, and 
no blanks will be automatically inserted into the string. The program- 
mer is responsible for ensuring that the spacing is correct. 

Any carriage return or line feed characters in the actual message 
text will be included in the resulting message string. The system does 
not automatically strip these characters. However, if each line of the 
message text is terminated with %0, the carriage returns and line feeds 
will be stripped from the text. 

Warning and error messages will be returned with their respective 
component IDs and message IDs prefixed to the beginning of the mes- 
sage, followed by a colon and a space. For example: 


XYZ0218: File ABC.DAT not found on machine SERVER1. 
All other message types will be returned as follows: 
File ABC.DAT not found on machine SERVER1. 


If the system cannot find the message file due to a DASD error, file 
not found error, or invalid message format condition, then a system- 
supplied error message will be substituted for the resulting message. 
The following error messages will be substituted for code page 850 
based on the following return codes: 


Error Returned Cause Substituted Msg Text 

ERROR MR MID NOT FOUND Could not find the SYS0317: The system cannot 
message ID in the find message %1 in message 
specified message file. file %2. 

ERROR_ FILE NOT FOUND The message file wasnot SYS0318: Message file %1 


found in the system root cannot be found. 
directory, the current 
directory, or the DPATH. 


ERROR MR UN_ACC_MSGF The device containing SYS0318:Message file %1 
the message file could cannot be found. 
not be accessed. 


ERROR_MR_INV_MSGF_FORMAT |The file specified is not SYS0319: The system cannot 
a message file or it is read message file %1. 
corrupted. 
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If the length of the file name exceeds the maximum allowed file 
name length on the system, the name is truncated to the maximum; 
and if the truncated name is not found, then ERROR FILE NOT_ 
FOUND is returned. 





DosInsertMessage Message Management 


Performs the appropriate string substitution for a previously loaded 
message. 


SYNTAX 


APIRET DosInsertMessage (PPCHAR ppchTable, ULONG ulVarCount, 
PSZ pszMessageln, ULONG ulMessage- 
InLen, PCHAR pchOutMessage, VLONG 
ulOutMessageLen, PULONG 
pulRkesulitMsgLen) 


PARAMETERS 


ppchTable - input 

A buffer containing an array of up to nine pointers to null-terminated 
SBCS or DBCS character strings. This value can be NULL if no substi- 
tution should be performed. 

ulVarCount - input 

The number of variable substitutions to be made. This number should 
match the number of strings in ppchTable. If there are no substitutions 
to be made, this should be zero. 

pszMessageln - input 

The address of a buffer containing the message to be processed. The 
message need not be a message previously loaded by DosGetMessage. 

ulMessagelnLen - input 

The length of the message pointed to by pszMessageln. 

pchOutMessage - output 

The address of a buffer to receive the resulting message after variable 
substitution is performed in the message body. 

ulOutMessageLen - input 

The length, in bytes, of the buffer pointed to by pchOutMessage. If the 
length of the buffer is too small to receive the resulting message string, 
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then as much of the message that will fit is placed into the buffer and 
ERROR MR MSG _TOO_LONG is returned. 

pulResultMsgLen - output 

The resulting length of the message after variable substitution has oc- 
curred. 


RETURNS 

0 NO_ERROR 320 ERROR MR INV_IVCOUNT 
316 ERROR MR MSG TOO LONG 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSMISC 

Ordinal: 4 DLL: MSG 

SEE ALSO 


DosGetMessage -190, DosPutMessage -195, DosQueryMessageCP -196 


NOTES 


DosInsertMessage is useful for dynamically creating messages in mem- 
ory, or performing the string substitution from a message loaded by 
DosGetMessage at a later time. DosInsertMessage substitutes the 
strings specified in ppchTable into the message body. If the message text 
is as follows: 


XYZ0218E: File %1 not found on machine $%2. 


and the substitution strings are ABC.DAT pointed to by index 0 in 
ppchTable, and SERVERI pointed to by index 1 in ppchTable, then the 
resulting string is returned: 


XYZ0218: File ABC.DAT not found on machine SERVER1. 


If wlVarCount is greater than 9, then no message processing occurs 
and ERROR _INV_IVCOUNT is returned. 

The text substitutions will be performed by matching the number 
value of the substitution symbol with index of the string in ppchTable. If 
a substitution symbol with a numeric value higher than ulVarCount is 
found, it is ignored and the substitution symbol will be left unchanged 
in the message. If the same substitution symbol appears more than 
once in the string, the substitution will occur for each occurrence of 
that same symbol. Substitution symbols do not have to appear in the 
message text in any particular order. 
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Substitution symbols do not have to be surrounded by blanks, and 
no blanks will be automatically inserted into the string. The program- 
mer is responsible for ensuring that the spacing is correct. 

Any carriage return or line feed characters in the actual message 
text will be included in the resulting message string. The system does 
not automatically strip these characters. However, if each line of the 
message text is terminated with %0, the carriage returns and line feeds 
will be stripped from the text. 

Warning and error messages will be returned with their respective 
component IDs and message [Ds prefixed to the beginning of the mes- 
sage, followed by a colon and a space. For example: 


XYZ0218: File ABC.DAT not found on machine SERVER1. 
All other message types will be returned as follows: 


File ABC.DAT not found on machine SERVER1. 





DosPutMessage Message Management 


Writes the specified message to a file or device. 


SYNTAX 

APIRET DosPutMessage (HFILE hfFile, ULONG ulMessageLen, 
PCHAR pchMessage) 

PARAMETERS 


hfFile - input 

The handle of the file or device to write to. 

ulMessageLen - input 

The length, in bytes, of the message pointed to by pchMessage. 
pchMessage - input 

The address of a buffer containing the message to write. 


RETURNS 

0 NO_ERROR 19 ERROR_WRITE_PROTECT 

6 ERROR_INVALID_ HANDLE 321 ERROR _MR_UN_ 
PERFORM 
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OTHER INFO 

Include file: bsedos.h Define: INCL_DOSMISC 
Ordinal: 5 DLL: MSG 

SEE ALSO 


DosGetMessage -190, DosInsertMessage -193, 
DosQueryMessageCP -196 


NOTES 


DosPutMessage assumes that the width of the screen is 80 characters, 
regardless of its actual width, and it assumes that the starting column is 
column 1. If a word crosses column 78, it is moved to column 1 of the 
next line. DBCS characters are not split even if they start as the last 
character on a line. 





DosQueryMessageCP Message Management 


Retrieves a list of code pages and language identifiers used in a mes- 
sage file or message segment. 


SYNTAX 


APIRET DosQueryMessageCP (PCHAR pchBuffer, ULONG ulBuffer- 
Len, PSZ pszMsgfilename, PULONG 
pulResultLen) 


PARAMETERS 

pchBuffer - output 

The address of a buffer to receive the code pages and language identi- 
fiers found in the message file. The returned data has the following 
format: 


Type Description 
USHORT Number of code pages. 


USHORT Code page ID. This field is repeated for the total number of 
code pages found in the message file or message segments. 


ULONG Language ID. The low-order word contains the language 
family, and the high-order word contains the specific version 
of the language (or sublanguage). 
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ulBufferLen - input 

The size of the buffer pointed to by pchBuffer, in bytes. 
pszMsgFilename - input 

The address of a buffer containing the null-terminated message file 
name. If no path is specified, then the system root directory, the cur- 
rent working directory, and the DPATH are searched. 

pulResultLen - output 

The length, in bytes, of the returned data. 


RETURNS 
0 NO_ERROR 318 ERROR MR _UN_ 
ACC_MSGF 
2 ERROR _ FILE NOT _ 319 ERROR MR _INV_MSGF _ 
FOUND FORMAT 
206 ERROR _ FILENAME _ 321 ERROR MR UN_ 
EXCED_RANGE PERFORM 

OTHER INFO 
Include file: bsedos.h Define: INCL_DOSMISC 
Ordinal: 8 DLL: MSG 
SEE ALSO 
DosGetMessage -190, DosInsertMessage -193, DosPutMessage -195 
NOTES 
Specify one of the following code pages: 
Code page Description 

437 United States 

850 Multilingual (Latin - 1) 

852 Latin 2 (Czechoslovakia, Hungary, Poland, Yugoslavia) 

857 Turkish 

860 Portuguese 

861 Iceland 

863 Canadian French 

865 Nordic 


952 *Japan 
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934 
936 
938 
942 
944 
946 
948 


*Korea 

*People’s Republic of China 
*Taiwan 

*Japan SAA 

*Korea SAA 

*People’s Republic of China SAA 
*Taiwan SAA 


The countries marked with an asterisk (*) are only supported on the Asian versions of OS/2 
running on Asian hardware. 


Specify one of the following language identifiers: 


Family Principal Country 


0 


oO O MO NT N OD OO Be Be OCF OCF FPO 


pm fe 
a © 


Sub- 
language 


0 
1 
1 


Oo =D 


Language 
Null 
Arabic 
Bulgarian 
Spanish 
Spanish Mexican 
Traditional Chinese 
Simplified Chinese 
Czech 
Danish 
German 
Swiss German 
Greek 
U.K. English 
U.S. English 
Finnish 


French 


Null 

Arab countries 
Bulgaria 

Spain 

Mexico 

Republic of China 
People’s Republic of China 
Czechoslovakia 
Denmark 
Germany 
Switzerland 
Greece 

United Kingdom 
United States 
Finland 


France 


1] 
11 
11 
12 
13 
14 
15 
15 
16 
17 
18 
18 
19 
19 
20 
al 
22 
22 
24. 
24 
25 
26 
27 
28 
ya 
30 
31 
a2 


me O©9 £x+DD 


Belgian French 
Canadian French 
Swiss French 
Hebrew 

Hungarian 

Icelandic 

Italian 

Swiss Italian 
Japanese 

Korean 

Dutch 

Belgian Dutch 
Norwegian—Bokmal 
Norwegian—Nynorsk 
Polish 

Portuguese 
Brazilian Portuguese 
Rhaeto-Romanic 
Serbo-Croatian (Cyrillic) 
Serbo-Croatian (Latin) 
Slovakian 

Albanian 

Swedish 

Thai 

Turkish 

Urdu 

Russian 


Catalan 
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Belgium 
Canada 
Switzerland 
Israel 
Hungary 
Iceland 
Italy 
Switzerland 
Japan 
Korea 
Netherlands 
Belgium 
Norway 
Norway 
Poland 
Portugal 
Brazil 
Switzerland 
Yugoslavia 
Yugoslavia 
Czechoslovakia 
Albania 
Sweden 
Thailand 
Turkey 
Pakistan 
U.S.S.R. 


Spain 
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Language and sublanguage identifiers with values 0 through 255 
are reserved for system use. Values 256 through 511 are available for 
application use. 

MKMSGF will verify that valid language and sublanguage identi- 
fiers are used. A zero indicates an unspecified language or sublanguage 
identifier. Only the values in the preceding table may be specified for 
values below 256. Values 256 through 511 are valid, and any value above 
511 is invalid. 





Nationa 
Language Support 





ational Language Support (NLS) is most easily achieved when the 

language considerations are a part of the initial design of an ap- 
plication. And although it can be cost prohibitive to retrofit a lan- 
guage-specific application, designing and writing a language-neutral 
application from the beginning is not an overwhelming task. However, 
there are many things to keep in mind when designing an NLS/DBCS- 
enabled application. Here is a noncomprehensive list of some of them: 


@ Any text to be displayed must be translatable. 

@ Translation of text can dramatically affect the length of the dis- 
played text. 

@ Different languages may not have certain characters, therefore, de- 
limiters and such should be a translatable resource. 

@ Icons and bitmaps may have different meanings in different coun- 
tries. In fact, some symbols may be offensive to peoples of other 
countries. 

@ All displayable resources (including accelerator tables) should be 
loaded from resource files (.rc) or message files. 
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® Some code pages may share some of the same characters, but they 
may have different code points. 

@ Different countries have different standards for how date, time, cur- 
rency, and so on are formatted, therefore, formatting of country- 
specific information must be dynamic. See DosQueryCtryInfo, pg. 
210. 

® Sorting routines must determine the collating sequence of a code 
page to determine the correct ordering of characters for the cur- 
rent country. See DosQueryCollate, pg. 209. 

@ lranslating a string from lowercase to uppercase and vice versa is 
usually not as simple as subtracting 32 from the value. See DosMap- 
Case, pg. 208. 


Additional considerations should be made for Double Byte 
Character Set (DBCS)-enabled applications: 


@ Double byte code pages may contain a mixture of single-byte and 
double-byte characters. 

@ All code pages, including DBCS code pages, use the same code 
point for a backslash (\) to indicate a subdirectory, but this charac- 
ter may appear as something else in different languages (such as the 
yen character in the Japanese code page). 

® Searching for individual SBCS characters in mixed code pages re- 
quire extra care. The search may return the second byte of a DBCS 
character instead of the SBCS character that was desired. Also, 
search routines need to increment and compare one or two charac- 
ters when searching strings using DBCS code pages. See DosQuery- 
DBCSEny, pg. 211. 


Anyone serious about NLS or DBCS enabling should contact IBM 
about its latest publications on the subject. It has several publications 
that go into great detail on NLS/DBCS. 

The preceding list may appear daunting, but many of the require- 
ments can be satisfied simply by placing language-specific information 
into resource files. There are a couple of different methods for attach- 
ing language-specific information to executables: 


@ The resources can be statically built into the executable. This means 
that the executable is language-specific and the application cannot 
dynamically change (while running) from one language to another. 

@ The resources may be built into a resource dynamic link library 
(DLL), with each language having its own DLL. All of the language 
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DLLs could be shipped with the application, and the installation 
routine could determine which DLL would be transferred to the 
hard disk. When the file is transferred, it is renamed to a nonlan- 
guage-specific name that the application will load when started. 
This method could also allow a program to switch languages while 
running. 


Code Pages 


A code page defines how the characters of a particular language are 
encoded. Each character has a specific value (also called a code point). 
For example, the letter x in code page 850 has a value of 97. Code page 
files include keyboard translation tables, display character sets, printer 
character sets, and country/language information. Double-byte code 
pages can contain several thousand characters. OS/2 allows applica- 
tions to dynamically select a code page that will be defined for their 
keyboard input, and screen and printer output. OS/2 does not sup- 
port all code pages. 





Code Page 850 


Presentation Manager uses code page 850 for its translatable re- 
sources. Code page 850 is also called the Latin-1 code page, which is a 
multilingual code page. Code page 850 contains the characters of the 
following 13 languages found in about 40 countries: 


Belgian French Canadian French Danish 
Dutch Flemish Finnish 
French German Italian 
Norwegian Portuguese Spanish 
LAD Spanish Swedish Swiss French 
Swiss German U.K. English U.S. English 





Code Page 437 


Code page 437 is the traditional or standard computer code page on 
the PC. U.S. versions of DOS and OS/2 (text sessions) use this code 
page as their default. The lower 128 characters contain the English 


204 


OS/2® Warp Control Program API 


character set including punctuation characters. The upper 128 char- 
acters contain the characters of several European countries and several 
graphic characters. Code page 437 is missing several accented charac- 
ters that are required by European characters, but most of these char- 
acters can be found in code page 850. 





Code Page Preparation and Switching 


During system initialization, the code pages specified in the CODE- 
PAGE statement of the CONFIG.SYS file will be readied to enable run- 
time switching of the display, keyboard, printer, and country informa- 
tion. Each device to be enabled for runtime switching must be defined 
in a DEVINFO statement in the CONFIG.SYS file for it to be prepared. 

If a device cannot be prepared for the requested code page during 
system initialization, it is prepared for the default code page as follows: 


Keyboard: ‘The keyboard layout defaults to the code page of the trans- 
lation table designated as the default layout in the KEYBOARD.DCP 
file. The default layout is based on the national code page of the as- 
sociated country. A DEVINFO statement must be specified in the 
CONFIG.SYS file for the KEYBOARD.DCP file. If the code page in- 
dicated in the CODEPAGE statement cannot be found in the KEY- 
BOARD.DCP file, the keyboard is prepared in the default code 
page. 

Display: The display defaults to the code page of the ROM_0 of the de- 
vice. The ROM_0 of the device is the native code page of the device 
or the lowest address of the ROM code page. 

Printer: The printer defaults to the code page of the ROM_0 of the de- 
vice. The ROM_0 of the device is the native code page of the device 
or the lowest address of the ROM code page. 

Country: The country information defaults to the code page of the 
first entry found in the COUNTRYSYS file for the country code. 
Each entry is the same information for a given country code, but it 
is encoded in a different code page. The first entry is based on the 
preferred country code page. If the country information cannot be 
found in the COUNTRYSYS file for a code page specified in the 
CODEPAGE statement, then it is prepared in the default code page. 
The COUNTRYSSYS file contains one default code page entry for 
each country code. 
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The system automatically switches the code pages of the display 
and printer to the code page of the program sending the output. 
Applications can switch the current code page by calling DosSet- 
ProcessCp, or query the current code page by calling DosQueryCp. 





@ Code Page Tags 


Each process has an associated code page tag that contains the current 
code page used by the process. When a process starts a child process, 
the child process inherits the code page of its parent. A process started 
in a new session will have the code page of the primary code page spec- 
ified in the CODEPAGE statement of the CONFIG.SYS file. When a 
process changes its code page, it does not affect the code page of its 
children. 


Code Page Functions 





DosQueryCp returns the current code page of the calling process and 
the pages that have been prepared by the system at boot time (pg. 205). 
DosSetProcessCp sets the current code page for the calling process 


(pg. 206). 





@® DosQueryCp NLS 


Returns the current process code page and the prepared system code 


pages. 

SYNTAX 

APIRET DosQueryCp(ULONG uwlListLen, PULONG pulCPList, 
PULONG pulReturnLen) 

PARAMETERS 


ulListLen - input 
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The length, in bytes, of the buffer pointed to by pulCPList. If the buffer 
is too small to contain the entire list, then the buffer is filled to its max- 
imum capacity and ERROR_CPLIST_TOO_SMALL is returned. 
pulCPList - output 

The returned list of code pages. The list has the following format: 


ULONG 1: The code page of the calling process. 

ULONG 2: The code page of the first (default) prepared system code 
page. 

ULONG 3: The code page of the second prepared system code page (if 
specified). 


pulReturnLen - output 
The length, in bytes, of the returned list. 


RETURNS 
0 NO_ERROR 474 ERROR CP NOT MOVED 
473 ERROR CPLIST_TOO_ SMALL 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSNLS 
Ordinal: 29] DLL: DOSCALLS 
SEE ALSO 


DosMapCase -208, DosQueryCollate -209, DosQueryCtryInfo -210, 
DosQueryDBCSEnv -211, DosSetProcessCp -206 


NOTES 


If 4 is specified for ulListLen, then only the current process code page 
is returned. The current process code page is set to either the code 
page of the parent process or the code page that was specified on a call 
to DosSetProcessCp. 

The code pages returned in the code page list appear in the order 
they were specified in the CODEPAGE statement in the CONFIG.SYS 
file. If no code pages have been prepared by the system, a zero is re- 
turned for the code page. 





DosSetProcessCp NLS 


Sets the code page of the calling process. 
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SYNTAX 
APIRET DosSetProcessCp (ULONG ulCodePage) 


PARAMETERS 


ulCodePage - input 
The code page to set for the calling process. 


RETURNS 

0 NO_ERROR 472 ERROR INVALID CODE_PAGE 
OTHER INFO 

Include file: bsedos.h Define: INCL _DOSNLS 

Ordinal: 289 DLL: DOSCALLS 

SEE ALSO 


DosQueryCollate -209, DosQueryCp -205, DosQueryCtryInfo -210, 
DosQueryDBCSEnv -211, DosSetProcessCp -206 


NOTES 
Changing the code page of a process has the following effects: 


1. The printer code page is set to match the process code page via the 
file system and the printer spooler (if installed) when the process 
requests to open the printer. This call will not affect any printers 
opened prior to this call, nor will it affect the code page of a printer 
opened by another process. 

2. Country-specific information will be retrieved based on the new 
code page. 

3. Any child processes created by the calling process will inherit the 
code page of the calling process. 


This call does not affect the code page of the keyboard or the dis- 
play. 


Country Dependent Functions 





DosMapCase case-maps a string of binary values that represent ASCII 
characters (pg. 208). 
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DosQueryCollate returns the collating sequence table that resides in 
the country file (pg. 209). 

DosQueryCtryInfo returns country-specific formatting information 
based on the country file (pg. 210). 

DosQueryDBCSEnv returns the DBCS environment vector that re- 
sides in the country file (pg. 211). 

DosQueryMessageCp returns the list of code pages and language 
identifiers used in the specified message file or message segment (see 
chapter six) (pg. 196). 





DosMapCase NLS 


Case-maps a string of binary values that represent ASCII characters. 


SYNTAX 


APIRET DosCaseMap(ULONG ulLength, PCOUNTRYCODE 
pecCountry, PCHAR pchBinary Values) 


PARAMETERS 

ulLength - input 

The length, in bytes, of the characters pointed to by pchBinaryValues. 
pecCountry - input 

The address of aCOUNTRYCODE structure that contains the country 
code and code page to use to perform the case-mapping. 
pchBinaryValues - input/output 

The address of a buffer containing a string of ASCII characters to be 
case-mapped. The case-mapping is performed in place so that the in- 


put characters will be overwritten. The characters can be SBCS or 
DBCS. 


RETURNS 
0 NO_ERROR 401 ERROR NLS _ TYPE _ 
NOT_FOUND 
397 ERROR NLS OPEN _ 476 ERROR CODE_PAGE__ 
FAILED NOT_FOUND 
398 ERROR NLS NO_CTRY CODE 
OTHER INFO 
Include file: bsedos.h Define: INCL. DOSNLS 


Ordinal: 7 DLL: NLS 
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SEE ALSO 


DosQueryCollate -209, DosQueryCp -205, DosQueryCtryInfo -210, 
DosQueryDBCSEnv -211, DosSetProcessCp -206 


NOTES 


Case-mapping is the process of converting the input characters to their 
uppercase counterparts. 

Case-mapping is performed based on the case-map provided in 
the COUNTRYSYS file for the selected country and code page. 





DosQueryCollate NLS 


Returns the collating sequence for the specified or current country 
code and code page. 


SYNTAX 


APIRET DosQueryCollate(ULONG u/Bu/Length, PCOUNTRYCODE 
pccCountry, PCHAR pchTableBuffer, 
PULONG pulReturnedLen) 


PARAMETERS 

ulBufLength - input 

The size, in bytes, of the buffer pointed to by pchTableBuffer. If the 
buffer is too small, then the buffer will be filled to its maximum capac- 
ity and ERROR_NLS_TABLE_TRUNCATED will be returned. 
pecCountry - input 

The address of a COUNTRYCODE structure that contains the country 
code and code page to use to perform the case-mapping. 
pchTableBuffer - output 

The address of a buffer that will receive the collating sequence table. 
The collating sequence table has the following format: 


Byte 1: The sort weight of the character with the ASCII value of 0. 
Byte 2: The sort weight of the character with the ASCII value of 1. 
Byte n: The sort weight of the character with the ASCII value of n. 
Byte 255: The sort weight of the character with the ASCII value of 255. 


If the buffer specified is bigger than necessary to contain the col- 
lating sequence table, then any unused spaced will be overwritten with 
ZeYOS. 
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pulReturnedLen - output 
The length, in bytes, of the returned collating sequence table. 


RETURNS 
0 NO_ERROR 399 ERROR NLS TABLE _ 
TRUNCATED 
397 ERROR NLS OPEN __ 401 ERROR _NLS_ TYPE _ 
FAILED NOT_FOUND 
398 ERROR NLS NO_CTRY_ 476 ERROR CODE_PAGE_ 
CODE NOT_FOUND 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSNLS 
Ordinal: 8 DLL: NLS 
SEE ALSO 


DosQueryCp -205, DosQueryCtryInfo -210, DosQueryDBCSEnv -211, 
DosMapCase -208, DosSetProcessCp -206 


NOTES 


This call searches the COUNTRYSYS file for the collating sequence 
table (for characters 0x00 through OxFF only) for the specified coun- 
try and code page. The SORT utility uses this function to determine 
the correct sort order for text. 





DosQueryCtryInfo NLS 


Returns country dependent formatting information. 


SYNTAX 


APIRET DosQueryCtryInfo (ULONG ulBufLen, PCOUNTRYCODE 
pecCountry, PCOUNTRYINFO 
pcaCountrylnfo, PULONG pulReturnLen) 


PARAMETERS 


ulBufLen - input 
The size, in bytes, of the buffer pointed to by paCowntrylnfo. If the size 
of the input buffer is too small to hold all of the data, the buffer is 
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filled to the maximum and ERROR _NLS_ TABLE TRUNCATED is re- 
turned. 

pecCountry - input 

The address of aCOUNTRYCODE structure that contains the country 
code and code page that will be queried for country information. 
peiCountryInfo - output 

The address of a COUNTRYINFO structure that will receive the coun- 
try-specific formatting information. 

pulReturnLen - output 

The size, in bytes, of the returned formatting information. 


RETURNS 
0 NO_ERROR 399 ERROR NLS _ TABLE, 
TRUNCATED 

397 ERROR NLS OPEN _ 401 ERROR NLS _ TYPE _ 
FAILED NOT_FOUND 

398 ERROR NLS NO_CTRY_ 476 ERROR CODE _PAGE_ 
CODE NOT_FOUND 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSNLS 

Ordinal: 5 DLL: NLS 

SEE ALSO 


DosMapCase -208, DosQueryCollate -209, DosQueryCp -205, 
DosQueryDBCSEnv -211, DosSetProcessCp -206 


NOTES 


This call returns information on the specified country code and code 
page from the information found in the COUNTRY-.SYS file. 





DosQueryDBCSEnv NLS 


Retrieves the DBCS environment vector from the COUNTRY-.SYS file. 


SYNTAX 


APIRET DosQueryDBCSEnv(ULONG uwlLength, PCOUNTRYCODE 
pecCountry, PCHAR pBu/ffer) 
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PARAMETERS 

ulLength - input 

The length, in bytes, of the buffer pointed to by pBuffer. For SBCS code 
pages, a length of 4 is sufficient, and 12 bytes is sufficient for DBCS 
code pages. If the buffer is sufficient to hold all of the retrieved data, 
the data will be terminated with 2 bytes of zeros. 

pecCountry - input 

The address of a COUNTRYCODE structure containing the country 
code and code page to query. 

pBuffer - output 

The address of a buffer to contain the returned information. If the in- 
formation to be returned is greater than the length specified by 
ulLength, then the buffer is filled to its maximum. If sufficient room ex- 
ists in the buffer, it will be terminated with 2 bytes of zeros. The envi- 
ronment vector has the following structure: 


Byte 1: The inclusive start value for the beginning of the range. 
Byte 2: The inclusive stop value for the end of the range. 


This structure is repeated for all of the defined ranges. The range 
definitions are terminated with 2 bytes of zeros. 


RETURNS 
0 NO_ERROR 399 ERROR NLS _ TABLE __ 
TRUNCATED 
397 ERROR NLS OPEN. 401 ERROR NLS _ TYPE __ 
FAILED NOT_FOUND 
398 ERROR NLS NO _CTRY_ 476 ERROR CODE_PAGE_ 
CODE NOT_FOUND 
OTHER INFO 
Include file: bsedos.h Define: INCL. DOSNLS 
Ordinal: 6 DLL: NLS 
SEE ALSO 


DosMapCase -208, DosQueryCollate -209, DosQueryCp -205, 
DosQueryCtryInfo -210, DosSetProcessCp -206 


NOTES 


DBCS characters are 2 bytes in length. The first byte of the characters 
must be between a certain range, and the second byte can be any value 
except NULL (indicates the end of a string). DosQueryDBCSEnv re- 
turns the valid range(s) for the first byte of a DBCS character. 
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DosQueryDBCSEnv determines the valid range by examining the 
COUNTRYSYS file and searching for the requested country code and 
code page. 


National Language Structures 





countrycode (ULONG) 0 
The country code. If 0 is specified, then the country code of the calling process is used. 
codepage (ULONG) 4 


The code page. If 0 is specified, then the code page of the calling process is used. 


Used by: DosMapCase -208, DosQueryCollate -209, DosQueryCtryInfo -210, 
DosQueryDBCSEnv -211 





countrycode (ULONG) 0 
The country code. 

codepage (ULONG) 4 
The code page. 

fsDateFmt (ULONG) 8 
The date format: 0 = mm/dd/yy, 1 = dd/mm/yy, 2 = yy/mm/dd. 

szCurrency[5] (CHAR) 12 
The currency indicator, null-terminated. 

szThousandsSeparator[2] (CHAR) 17 
The thousands separator, null-terminated. 

szDecimal[2] (CHAR) 19 
The decimal separator, null-terminated. 

szDateSeparator[2] (CHAR) 21 


The date separator, null-terminated. 
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szTimeSeparator[2] (CHAR) 23 
The time separator, null-terminated. 
szCurrencyFmt (UCHAR) 25 
A bit field as follows: 
Bit Description 
0 If on, the currency indicator follows the money value. If off, the cur- 


rency indicated precedes the money value. 


] The number of spaces between the currency indicator and the money 
value—either 0 or 1. 


2 If set, the first two bits are ignored, and the currency indicator replaces 
the decimal indicator. 


cDecimalPlaces (CHAR) 26 
The number of decimal places used in currency notation. 
fsTimeFormat (UCHAR) ri 


The time format used in director listings: 1 = 24 hour clock, 2 = 12 hour clock with 
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an “a” or “p.” 


abReserved1[2] (USHORT) 28 
Reserved. This will be set to zero. 

szDataSeparator[2] (CHAR) 32 
The data list separator, null-terminated. 

abReserved2[5] (USHORT) 34 


Reserved. This will be set to zero. 


Used by: DosQueryCtryInfo -210 








S/2 supports both named and unnamed pipes for interprocess 
communication. 


Unnamed Pipes 


Unnamed pipes, sometimes called anonymous pipes, are one-way 
pipes that can be used only for communication with child (related) 
processes on the same computer or for communication within the 
same process. The data for unnamed pipes is stored in a circular buffer 
with read and write pointers maintained by the system. When creating 
the pipe, two separate handles are returned for reading and writing to 
the pipe. There are no access permissions required for unnamed 
pipes, and data read from or written to the pipe is not checked or mod- 
ified in any way by the system. 


Redirecting the Standard Input and 
Standard Output of a Child Process 


Unnamed pipes are often used to redirect the standard input (STDIN) 
and standard output (STDOUT) of a child process to its parent. This 
is done by creating the unnamed pipe using DosCreatePipe, then us- 
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ing DosDupHandle to duplicate (that is, replace) the standard output 
handle with the write handle of the pipe. This will cause the STDOUT 
of the child process to be written to the pipe instead of the screen. 
Another unnamed pipe can be created to allow the parent process to 
write to a pipe and have this data appear to the child process as stan- 
dard input. This is done by replacing STDIN with the read handle of 
the second pipe. After STDOUT and STDIN have been replaced with 
the pipe handles, the child process can then be started using Dos- 
ExecPgm. Close the extra pipe handles, and use the remaining pipe 
handles to read the child’s STDOUT and write to the child’s STDIN. If 
desired, the STDIN and STDOUT of the child process can be saved by 
duplicating the handle before being replaced so that it can be restored 
later. 


Named Pipes 


Named pipes are full-duplex pipes that can be used between two or 
more related or unrelated processes. The processes may even exist on 
two different computers on a network. Using named pipes across a 
LAN requires that either the server process is running on a server, or, 
if IBM Lan Requester 3.0 is used, that peer services have been installed 
on the two machines that will be communicating with each other (see 
“LAN Considerations”). Unlike unnamed pipes, named pipes have two 
buffers (read and write) that are referenced via the same handle. 

A named pipe is set up on a server process that one or more client 
processes can connect to. The pipe can be set up as an inbound pipe, 
an outbound pipe, or as a full-duplex pipe. The server process that cre- 
ates the pipe determines what kind of duplexing the pipe will support, 
as well as the number of clients that will be simultaneously supported. 
Named pipes are created by calling DosCreateNPipe. 





Pipe Names 


Pipe names must have the following form: \PIPE\PipeName. Case is 
not important, but file system naming conventions must be respected. 
Clients who wish to connect to remote named pipes must prefix the 
pipe name with the computer name of the server (such as, \Computer- 
Name\Pipe\MyPipe). 
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Although pipe names are exposed across the LAN for the purpose 
of connection, they are not exposed across the LAN when they are cre- 
ated. This means that multiple pipes of the same name can be created 
on the same LAN with only their computer names differentiating 
them. This could be useful when one server machine would not be ad- 
equate to handle the load of numerous client requests. A secondary 
server could be set up to handle some of the requests. Of course, a 
method for determining which server a client would connect to would 
need to be devised. 





Pipe Instances 


Each client that needs to be simultaneously connected to the pipe re- 
quires an additional “instance” of the pipe. A pipe instance is a unique 
handle with its own buffers that are used by a client process to com- 
municate with a particular named pipe. The server process creates 
pipe instances by repeated calls to DosCreateNPipe. The fact that a 
client may be using one of many pipe instances is transparent to the 
client. The client is only aware that it connected to pipe \PIPE\x. 
Clients connect to named pipes by calling DosOpen. If there are no 
pipe instances available when a client requests access to a named pipe, 
it can block on the pipe (using DosWaitNPipe) until an instance is 
available. The number of pipe instances that will be supported by the 
server process is specified at the time the pipe is created. 

After a named pipe is created, the server must place an instance of 
the pipe in listening mode for each client that will be simultaneously 
supported. Listening mode simply means that the server is ready and 
waiting for a client to connect to the pipe so that communication can 
begin. Listening mode is entered by calling DosConnectNPipe. 
Typically, the Server will create a separate thread for each simultane- 
ously supported instance and then begin listening. Another scheme is 
to start just a couple of threads in the beginning and then, when an in- 
stance is connected, start another thread to go into listening mode so 
that there will always be a pipe instance available. 

If a client connects to a pipe, and later closes the pipe (see 
DosClose), the server process must reinitialize the pipe instance before 
it can be used again by another client. To do this, the server process 
should acknowledge the client close by calling DosDisConnectNPipe, 
and then call DosConnectNPipe to begin listening again. 
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@ Byte vs. Message Pipes 


A named pipe must be defined as either a byte pipe or a message pipe. 
Byte pipes treat data as an undifferentiated sequence of bytes. Message 
pipes treat data as a collection of bytes that is read and written as a 
block. Pipes also have modes associated with them that define how the 
data will be read from them: message-read mode and byte-read mode. 
Message-read mode specifies that data will be read from the pipe as a 
collection of bytes that must be read in its entirety, while byte-read 
mode indicates that the data read from the pipe is an undifferentiated 
sequence of bytes that may be read in portions. Message pipes can be 
read in either message-read mode or byte-read mode, but byte pipes 
must always be read in byte-read mode. 

Data written to a message pipe will be prefixed with a two-byte 
header that contains the length of the message. The header is auto- 
matically stripped by the system when the message is read (see 
DosRead pg. 225). The type of pipe to be created (byte or message) is 
specified at creation time. Named pipes are always opened in the same 
read mode that was specified by the server when the pipe was created. 

Named pipes can be created so that they will be read from or writ- 
ten to synchronously or asynchronously. Regardless of the type of pipe 
created (blocking or nonblocking), the client process issuing 
DosOpen will always open the pipe in blocking mode (an attempt to 
do otherwise returns an error). The blocking mode of a pipe can be 
changed by calling DosSetNPHState. 


Transaction Processing and 
Remote Procedure Calling 


OS/2 provides two APIs that combine several calls into one, which fa- 
cilitates transaction processing and local and remote procedure call- 
ing (RPC) via named pipes. DosTransactNPipe may be used on full-du- 
plex message pipes to provide transaction processing for persistent 
connections. The call will first issue a DosWrite, and then block on a 
DosRead until an aknowledgment is read from the pipe. 

DosCalINPipe combines the DosOpen, the DosTransactNPipe, and 
DosClose calls into one operation. DosCallNPipe is much more effi- 
cient than calling these APIs separately, and is excellent for nonpersis- 
tent connections since it reduces the number of simultaneous pipe in- 
stances that must be supported. 
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Synchronization 


Synchronization of nonblocking named pipes is necessary to notify the 
nonblocking thread that data is available for reading, or space is avail- 
able for writing. This is done by attaching an event semaphore to the 
pipe using DosSetNPipeSem and then blocking on the semaphore by 
calling DosWaitEventSem. Two semaphores can be attached to a 
named pipe—one to the server end and one to the client end. This al- 
lows the client and the server to receive their own notifications without 
disturbing the other. The system will post the semaphore whenever 
data has arrived or whenever write space is available. 

DosResetBuffer may be used to synchronize read-write dialogs. 
DosResetBuffer will block after a call to DosWrite until the data has 
been read by the other process. 


DOS Clients 


DOS programs can access OS/2 named pipes by treating them as files. 
The C library function _sopen( ) should be used, and the pipe should 
be opened in binary mode. Once the file is opened, read( ) and write 
( ) may be used to read and write data respectively. Use of buffered 
stream routines should be avoided, since they may cause unpredictable 
results. DOS clients on Netware requesters may require an additional 
DLL to support this feature. 


LAN Considerations 


Named pipes across LANs may have some small aberrations in behav- 
ior. These aberrations can manifest themselves as anything from occa- 
sional unexpected errors to poor performance. The reason is that 
each LAN system developer must implement the named pipe opera- 
tions so that they work on his or her LANs. So, while the interface for 
named pipes may be identical regardless of the LAN system, the guts 
may not. Therefore, it is highly recommended that software imple- 
menting named pipes be tested on the different LANs that will be sup- 
ported. 

Some LAN systems may require additional software and special 
system configuration before named pipes can be used. Consult your 
LAN system’s documentation for additional information about the use 
of named pipes. 
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Warnings and Restrictions 


@® [he maximum size of the read and write buffers of a named pipe is 
65535 bytes. 

@ Unnamed pipes can only be used within the same process and be- 
tween related processes. 

@ Named pipes that are used across a network must be opened by pre- 
fixing the pipe name with the computer name of the server or peer 
machine, for example: \ComputerName\Pipe\MyPipe. 


Nonspecific Pipe Functions 





DosClose closes a pipe (pg. 220). 

DosDupHandle creates or assigns a new handle for an existing pipe 
(pg. 221). 

DosOpen opens a pipe for a client process (pg. 223). 

DosRead reads data from a pipe (pg. 225). 

DosWrite writes data to a pipe (pg. 227). 





@ DosClose Pipes 


[Pipe-specific Information Only] 
Closes a named or unnamed pipe. 


SYNTAX 
APIRET DosClose (HFILE h/PipeHandle) 


PARAMETERS 

hfPipeHandle - input 

The handle of the named or unnamed pipe to close. For named pipe 
handles, this value must be cast to an HFILE. 


RETURNS 


0 NO_ERROR 5 ERROR_ACCESS_DENIED 
2 ERROR_FILE_NOT_FOUND 6 ERROR_INVALID_ HANDLE 
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OTHER INFO 

Include file: bsedos.h Define: INCL_DOSFILEMGR 
Ordinal: 257 DLL: DOSCALLS 

SEE ALSO 


DosCreateNPipe -235, DosDisConnectNPipe -239, DosOpen -223 


UNNAMED PIPE NOTES 


For unnamed pipes, both the read and the write handle must be closed 
before the pipe is freed from the system. To avoid errors, it is a good 
idea to close the write handle first. The pipe is not deleted from mem- 
ory until all handles referring to the pipe (including duplicated han- 
dles) are closed. 


NAMED PIPE NOTES 


When all handles that refer to one end of anamed pipe are closed, the 
pipe is considered broken. 

If the server closes a pipe that is still opened by a client, and the 
pipe contains data written by the server, it will remain in the pipe for 
reading by the client. 

After the client closes its end of a named pipe, the server process 
should issue a DosDisConnectNPipe to acknowledge the close. The 
server may then call DosConnectNPipe to go back into listening state 
or call DosClose to free the resources allocated for the pipe. The re- 
sources will not actually be freed unless all the client handles have 
been closed as well. 

If the server end of a broken pipe closes, the named pipe is immedi- 
ately deallocated; otherwise, it is not deallocated until all client 
processes close the pipe. 





DosDupHandle Pipes 


[Pipe-specific Information Only] 
Creates a duplicate file handle for an open file or pipe. 


SYNTAX 
APIRET DosDupHandle(HFILE hfHandle, PHFILE phfNewHandle) 


222 


OS/2® Warp Control Program API 


PARAMETERS 

hfHandle - input 

The file or pipe handle to be duplicated. For named pipes, the handle 
must be cast to an HFILE. 

phfNewHandle - input/output 

On Input, the address of an HFILE that contains the method of dupli- 
cation: 


Value Description 
OxFFFFFFF Allocate a new file handle. 
not OxFFFFFFFF Close the old handle and assign this value as the 


new handle of the pipe. This value can be any 
currently valid file/pipe handle accessible to the 
process including any of the standard I/O handles. 
The standard I/O handles are: 


0 Standard In 
1 Standard Out 
2 Standard Error 


On Output, if OxFFFFFFFF was specified, then phfNewHandle will 
contain the new handle allocated by the system. 


RETURNS 

0 NO_ERROR 6 ERROR INVALID HANDLE 

4 ERROR TOO MANY, 114 ERROR INVALID _ 
OPEN_FILES TARGET HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSFILEMGR 

Ordinal: 260 DLL: DOSCALLS 

SEE ALSO 


DosClose -220, DosCreatePipe -230, DosDupHandle -221, 
DosOpen -223, DosRead -225, DosSetMaxFH -98, 
DosSetRelMaxFH -99, DosWrite -90 


NOTES 


Duplicating a pipe handle causes a link to be created between handle- 
specific information. Therefore, if the read pointer for one handle 
moves, it will also move for the duplicated file handle and vice versa. 
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However, if hfHandle is closed, it will not affect the duplicate handle. 
When the child process terminates, the phfNewHandlewill be closed au- 
tomatically. 

Ifa handle of a currently open pipe is specified for phfNewHandle, 
it is closed before being redefined as the duplicate handle. 





DosOpen Named Pipes 


[Pipe-specific Information Only] 
Opens a named pipe for a client process. 


SYNTAX 


APIRET DosOpen(PSZ pszPipeName, PHFILE phf{PipeHandle, 
PULONG pulActionTaken, ULONG ulFileSize, 
ULONG uwlFileAtinbute, ULONG ulOpenOption, 
ULONG wlOpenMode, PEAOP2 pEABu/f) 


PARAMETERS 

pszPipeName - input 

A pointer to a buffer containing the null-terminated name of the pipe 
to open. 

phfPipeHandle - output 

The address of an HFILE that will receive the pipe handle. 
pulActionTaken - output 

The address of a ULONG to receive the action taken. For named 
pipes, this call always returns a value of FILE_EXISTED if the call was 
successful. You may not specify a NULL for this parameter. 

ulFileSize - input 

For named pipes, specify OL. 

ulFileAttribute - input 

Specify FILE_NORMAL for named pipes. 

ulOpenOption - input 

Specify FILE_OPEN for named pipes. 

ulOpenMode - input 

The access mode must be the same as specified on the DosCreate- 
NPipe call. The read mode and blocking mode are ignored. For read 
mode, it is set to the read mode that was specified when the pipe was 
created; for blocking mode, it is set to block regardless of what was spec- 
ified when the pipe was created. The following mode options apply for 
named pipes (the default is in italics): 
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Constant Description 


Access modes: 


OPEN_ACCESS_READONLY 0x0000 Open the pipe for reading. 

OPEN_ACCESS_WRITEONLY 0x0001 Open the pipe for writing. 

OPEN_ACCESS_READWRITE 0x0002 Open the pipe for reading 
and writing. 


Sharing modes: 


OPEN_SHARE_DENYREADWRITE 0x0010 No other client may open the 


pipe. 
OPEN_SHARE_DENYWRITE 0x0020 No other client may open the 
pipe for writing. 
OPEN SHARE DENYREAD 0x0030 No other client may open the 
pipe for reading. 
OPEN SHARE DENYNONE 0x0040 Deny neither read nor write 
access. 
pEABuf - input 
Specify NULL for named pipes. 
RETURNS 
0 NO_ERROR 65 ERROR_NETWORK_ ACCESS_ 
DENIED 
3 ERROR_PATH_NOT_ 67 ERROR_BAD_NET_PATH 
FOUND 
5 ERROR_ACCESS_ 231 ERROR_PIPE_BUSY 
DENIED 
12 ERROR_INVALID_ACCESS 
OTHER INFO 
Include file: bsedos.h Define: ,INCL_DOSFILEMGR, 
INCL_DOSNMPIPES 
Ordinal: 273 DLL: DOSCALLS 
SEE ALSO 


DosClose -220, DosConnectNPipe -234, DosCreateNPipe -235, 
DosRead -225, DosSetNPHState -247, DosWrite -227 
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NOTES 


If an invalid access mode was specified (such as OPEN_ACCESS_ READ- 
WRITE on an INBOUND or OUTBOUND only pipe) then ERROR_AC- 
CESS _DENIED is returned. 

If no sharing mode was specified, then ERROR_INVALID_AC- 
CESS is returned. 

If the pipe to open is remote and the required LAN software is not 
installed, is improperly installed, or the appropriate access rights have 
not been assigned, then ERROR_NETWORK_ACCESS_DENIED is re- 
turned. 

If the server process is not in a listening state or there are no more 
instances available, then ERROR_PIPE BUSY is returned. 

If a nonexisting pipe is specified for pszPipeName, then ERROR_ 
PATH _NOT_FOUND is returned. This error is also returned if NP_ 
NOWAIT is specified. It is an error to specifiy the NP_NOWAIT option 
regardless of whether the pipe was created as a blocking pipe or a 
nonblocking pipe. Blocking mode may only be set for a client via 
DosSetNPHState. 

Read mode for a client is always opened as the same read mode as 
that set when the server created the pipe. The client must call 
DosSetNPHState to change it. 

If the pipe name specified included an incorrect remote com- 
puter name, then ERROR_BAD_NET_PATH is returned. 





DosRead Pipes 


Reads data from a named or unnamed pipe. 


SYNTAX 


APIRET DosRead (HFILE hfPipeHandle, PVOID pReadBuffer, ULONG 
ulReadBufferLen, PULONG pulBytesRead) 


PARAMETERS 

hfPipeHandle - input 

The handle of the pipe to read from. For named pipes, the handle 
must be cast to an HFILE. 

pReadBuffer - output 

A pointer to a buffer that will receive the data read from the pipe. 
ulReadBufferLen - input 

The length, in bytes up to 65535, of the buffer pointed to by 
pReadBuffer. DosRead will attempt to read this number of bytes. 


226 OS/2® Warp Control Program API 


pulBytesRead - output 
The address of a ULONG that will receive the actual number of bytes 


read. 
RETURNS 
0 NO_ERROR 232 ERROR NO_ DATA 
6 ERROR INVALID _ 233 ERROR PIPE NOT _ 
HANDLE CONNECTED 
109 ERROR BROKEN PIPE 234 ERROR MORE DATA 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 281 DLL: DOSCALLS 
SEE ALSO 


DosCallNPipe -231, DosClose -220, DosCreatePipe -230, 
DosCreateNPipe -235, DosOpen -223, DosTransactNPipe -251, 
DosWrite -227 


NOTES 


The following table shows the expected result based on the type of 
pipe, the read mode, and the amount to read: 


Pipe Read 
Type Mode Amount to Read Result 


Message Message >=size ofthe message ‘The full message is read and 
ulBytesRead is set to the size of 
the message. 


Message Message <sizeofthe message — Returns the requested 
number of bytes and a return 
code of ERROR_MORE - 
DATA. 


Message Byte <=> size of the message The message header is 
stripped and DosRead acts as 
if it were reading a byte pipe. 


Byte Byte <=> size of the message ‘The data is read up to the 
number of bytes specified in 
ulBufferReadLen, and 
ulBytesRead is set to the 
number of bytes returned. 
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If the pipe is set for blocking mode, then any read operation will 
block until data is available to read. DosRead will never return with 
ulBytesRead equal to zero unless at the end of the file (the server issued 
a DosDisConnectNPipe), in which case it will return ERROR_PIPE_ 
NOT_CONNECTED. When reading message pipes in message-read 
mode, the message is always read in its entirety unless the message is 
larger then the amount specified to read. 

In nonblocking mode, the pipe will return ERROR_NO_DATA 
and ulBytesRead will be zero if there was no data available at the time 
the call was made. 


RESTRICTIONS/WARNINGS 


@ If the data that is read appears corrupted, the data may have been 
written to the pipe from a nontiled buffer (see Restrictions/ 
Warnings in DosWrite, page 229, for more information), or the data 
to be read is message data and the process is in byte-read mode. 





DosWrite Pipes 


Writes data to the specified pipe handle. 


SYNTAX 


APIRET DosWrite (HFILE hfPipeHandle, PVOID pOutBuffer, ULONG 
ulOutBufferLen, PULONG pulBytesWnitten) 


PARAMETERS 

hfPipeHandle - input 

The handle of the pipe to write to. For named pipes, cast the pipe han- 
dle as an HFILE. 

pOutBuffer - input 

A pointer to a buffer containing the data to be written to the pipe. 
ulOutBufferLen - input 

The amount of data, in bytes up to 65535, to write to the pipe. 
pulBytesWritten - output 

The actual number of bytes written to the pipe. 


RETURNS 


OQ NO_ERROR 33. ERROR_LOCK_VIOLATION 
5 ERROR_ACCESS DENIED 109 ERROR BROKEN PIPE 
6 ERROR_INVALID HANDLE 157 ERROR DISCARDED 
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19 ERROR WRITE_ 233, ERROR PIPE NOT _ 
PROTECT CONNECTED 

29 ERROR WRITE FAULT 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSFILEMGR 

Ordinal: 282 DLL: DOSCALLS 

SEE ALSO 


DosClose -220, DosCreateNPipe -235, DosRead -225 


NAMED PIPE NOTES 


DosWrite may be used to write to message and byte pipes. When writ- 
ing messages to a message pipe, DosWrite automatically encodes the 
message length at the beginning of the message. The message length 
will be stripped automatically by DosRead. 

If an attempt is made to write to a broken pipe (that is, the server 
called DosDisconnectNPipe or the pipe was never connected in the 
first place), the call returns with ERROR_BROKEN_ PIPE. 

If the write operation is interrupted by a signal exception, then 
ERROR DISCARDED is returned. 

If the call is issued against a closed pipe handle (the server called 
DosClose) or a bogus handle, it will return ERROR_INVALID_HAN- 
DLE. 

If the server attempts to write to a pipe that has been closed by the 
client process, ERROR_DISCARDED will be returned. If the client at- 
tempts to write to a pipe that has been closed by the server process, ER- 
ROR_BROKEN_PIPE will be returned. 

The following table shows the expected result based on the type of 
pipe, the blocking mode, and the amount of data to write: 


Pipe Blocking 
Type Mode Size of Data Result 


Message Blocking <=> size of the pipe Returns only after writing all 
of the requested bytes. The 
call may have to wait for part 
of the message to be read 
before writing the entire 
message. 


Message Nonblocking > size of the pipe Returns only after writing all 
of the requested bytes. The 


Message Nonblocking <= size of the pipe 


Byte 


Byte 


Blocking <=> size of the pipe 


Nonblocking <=> size of the pipe 


RESTRICTIONS/WARNINGS 


@ The outbound data buffer must not cross a 64k boundary, and the 
message must be aligned on a doubleword boundary. Memory allo- 
cated using DosAllocMem should be performed using the OBJ_ 
TILED bit. If the memory is allocated using malloc, then the com- 
piler documentation should be checked for methods for allocating 
tiled memory using malloc. (Note: Current versions of OS allocate all 
memory as tiled memory whether it is requested or not.) 
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call will have to wait for part 
of the message to be read 
before writing the entire 
message. 


If there is enough room in 
the pipe buffer, the call 
writes all of the data and 
returns with ULBytesWniten 
set to the number of bytes 
written. If there isn’t enough 
room, then the call returns 
with ulBytesWritten equal to 
Zero. 


The call will return only after 
writing all the requested 
bytes to the pipe. The call 
may have to wait for some of 
the data to be read before 
returning if the pipe is 
smaller than the byte stream 
to be written or there is not 
enough room in the pipe. 


The call will try to write 
ulOutBuffer bytes to the pipe. 
If there is not enough room 
in the pipe, it will write as 
much as possible and return. 
Check ulBytesWritten for the 
actual number of bytes 
written to the pipe. 
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Unnamed Pipe Functions 





DosCreatePipe creates an unnamed pipe (pg. 230). 





@ DosCreatePipe Unnamed Pipes 


Creates an unnamed pipe. 


SYNTAX 


APIRET DosCreatePipe (PHFILE phfReadHandle, PHFILE 
phf{fWnteHandle, ULONG ulPipeSize) 


PARAMETERS 


phfReadHandle - output 

The addres of an HFILE that will receive the read handle of the un- 
named pipe. 

phfWriteHandle - output 

The address of an HFILE that will receive the write handle of the un- 
named pipe. 

ulPipeSize - input 

The size, in bytes up to 65535, of the pipe buffer. If zero is specified, a 


512-byte buffer is used. 

RETURNS 

0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 
87 ERROR_INVALID_PARAMETER 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSQUEUES 
Ordinal: 239 DLL: DOSCALLS 

SEE ALSO 


DosClose -220, DosDupHandle -221, DosRead -225, DosWrite -227 


NOTES 


Unnamed pipes can only be used between related processes (par- 
ent/child). 
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If the system cannot allocate its internal structures or the pipe 
buffer, then ERROR_NOT_ENOUGH_MEMORY is returned. 

The size of the pipe specified in ulPipeSize is only a recommenda- 
tion to the system. The actual size of the pipe will depend on available 
memory. If the value specified for wlPipeSize is greater than 65535, then 
ERROR INVALID PARAMETER is returned. 





DosCalliINPipe Named Pipes 


Performs a local or remote procedure call on a message pipe. 


SYNTAX 


APIRET DosCallNPipe(PSZ pszPipeName, PVOID plnBuffer, ULONG 
ullnBufferLen, PVOID pOutBuffer, ULONG 
ulOutBufferLen, PULONG pulBytesOut, 
ULONG wlTimeOut) 


PARAMETERS 

pszPipeName - input 

A pointer to a buffer containing the null-terminated string of the pipe 
to be opened. All pipe names must be prefixed with \Pipe\, and must 
conform to normal file-naming conventions. If the pipe to communi- 
cate with is a remote pipe, then the prefix must include the computer 
name of the server process as well (such as \ComputerName\ 
Pipe\MyPipe). The case of the \Pipe\ prefix is not important. Don’t for- 
get that, in C and C++, the slashes must be doubled for string literals. 
pinBuffer - input 

A pointer to a buffer containing the data that is to be written to the 
pipe. 

ullnBufferLen - input 

The length, in bytes up to 65535, of the buffer specified in pln Buffer. 
pOutBuffer - output 

A pointer to a buffer that will receive the return data. 

ulOutBufferLen - input 

The length, in bytes up to 65535, of the buffer specied in pOutBuffer. 
pulBytesOut - output 

The address of a ULONG that will receive the actual number of bytes 
written to pOutBuffer. 
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ulTimeOut - input 
The maximum time, in milliseconds, to wait for a pipe instance to be- 
come available before timing out. 


RETURNS 

0 NO_ERROR 230 ERROR BAD PIPE 

2 ERROR FILE NOT_ 231 ERROR PIPE BUSY 
FOUND 

11 ERROR BAD FORMAT 233 ERROR PIPE NOT_ 

CONNECTED 

95 ERROR INTERRUPT 234 ERROR MORE DATA 

OTHER INFO 

Include file: bsedos.h Define: INCL. _DOSNMPIPES 

Ordinal: 240 DLL: DOSCALLS 

SEE ALSO 


DosConnectNPipe -234, DosDisConnectNPipe -239, DosClose -220, 
DosCreateNPipe -235, DosOpen -223, DosRead -225, 
DosSetNPipeSem -249, DosTransactNPipe -251, DosWrite -227 


NOTES 


This call provides the semantics of local and remote procedure calling 
by issuing a DosOpen followed by a DosWrite, then a DosRead, and fi- 
nally a DosClose. 

If an invalid pipe name is given, ERROR_FILE_NOT_FOUND is 
returned. 

If the buffer pointed to by pOutBuffer is too small, ERROR_ 
MORE_ DATA is returned. 

If there are no pipe instances available or an exception (or signal) 
occurs, then ERROR_INTERRUPT is returned. 

If the server process is not in a listening state, then ERROR_ 
PIPE BUSY is returned. 

If this call is attempted on a nonfull-duplex message pipe, then 
ERROR BAD FORMAT is returned. 


RESTRICTIONS/WARNINGS 


@ It is possible that the server process may issue a DosDisConnect- 
NPipe before the client processing of DosCallNPipe performs its 
close operation. In this case, DosCallNPipe will return ERROR_ 


Pipes Zoo 


PIPE_NOT_CONNECTED; however, pulBytesOut should be checked 
to see if any data was returned. This scenario can be avoided by 
attaching an event semaphore to the pipe (see DosSetNPipeSem 
pe. 249). 

@ For message pipes the outbound data buffer must not cross a 64k 
boundary, and the message must be aligned on a doubleword 
boundary. 


Named Pipe Functions 





DosCalINPipe performs a DosOpen, DosTransactNPipe, and DosClose 
in one step. This provides the semantics of a local or remote procedure 
call (pg. 231). 

DosConnectNPipe places the server process in a listening state (pg. 
20%). 

DosCreateNPipe creates a named pipe (pg. 235). 
DosDisConnectNPipe acknowledges that a client process has closed its 
end of a named pipe (pg. 239). 

DosPeekNPipe examines the data in the pipe without removing it. It 
also returns the state of the pipe (pg. 240). 

DosQueryNPHState returns information specific to a named pipe 
handle (pg. 242). 

DosQueryNPipelInfo returns information that is global to all instances 
of anamed pipe (pg. 244). 

DosQueryNPipeSemState returns information about the pipes to which 
a given semaphore is attached (pg. 245). 

DosResetBuffer blocks the calling thread until all written data has 
been read from the other end of the pipe (pg. 247). 

DosSetNPHState sets the blocking mode and read mode of a pipe (pg. 
247). 

DosSetNPipeSem attaches a shared event or muxwait semaphore to a 
named pipe (pg. 249). 

DosTransactNPipe performs a DosWrite, and then a DosRead on a 
full-duplex message pipe. The call automatically places the pipe han- 
dle into blocking mode (pg. 251). 

DosWaitNPipe waits for an instance of a named pipe to become avail- 


able (pg. 253). 
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@ DosConnectNPipe Named Pipes 


Places the server process of a named pipe into the listening state. 


SYNTAX 
APIRET DosConnectNPipe(HPIPE hpPipe) 


PARAMETERS 
hpPipe - input 
The handle of a named pipe to begin listening for. 


RETURNS 
0 NO_ERROR 230 ERROR_BAD_ PIPE 
95 ERROR_LINTERRUPT 233 ERROR_PIPE_NOT_ 
CONNECTED 
109 ERROR_BROKEN_ PIPE 
OTHER INFO 
Include file: bsedos.h Define: INGL_DOSNMPIPES 
Ordinal: 241 DLL: DOSCALLS 
SEE ALSO 


DosClose -220, DosCreateNPipe -235, DosDisConnectNPipe -239 


NOTES 


Before a connection to an instance of a named pipe can be made, the 
pipe must first be placed into the listening state by the server process. 
This call must subsequently be made after each instance is connected 
to make sure the next instance is available for connection by a client 
process. 

If the client process attempts this call, ERROR_BAD_PIPE is re- 
turned. 

The following state table shows the behavior of this call depending 
on the blocking mode of the pipe, whether a connection already exists, 
and whether an instance of the pipe is already in the listening state: 


Mode State Result 


Blocking Not connected The call will block until a client process 
connects to the pipe (see DosOpen 


pg. 223). 
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Blocking Connected The call returns immediately with a code 
of NO_ERROR. 
Nonblocking Not connected The first time the call is made, it will 


return immediately with 
ERROR_PIPE_NOT_CONNECTED; 
however, the pipe is placed into the 
listening state. Subsequent calls to 
DosConnectNPipe may be used to check 
whether the pipe is connected. 


Nonblocking Connected The call returns immediately with a 
return code of NO_ERROR. 


The server must first disconnect a pipe (see DosDisConnectNPipe 
pg. 239) closed by the client before calling DosConnectNPipe, other- 
wise ERROR BROKEN _ PIPE is returned. 

If the function is interrupted while waiting for a client connec- 
tion, ERROR_INTERRUPT is returned. This can occur from an ex- 
ception or a no-wait I/O request that has finished. 





DosCreateNPipe Named Pipes 


Creates a named pipe. 


SYNTAX 


APIRET DosCreateNPipe (PSZ pszPipeName, PHPIPE phPipe, ULONG 
ulOpenMode, ULONG ulPipeMode, ULONG 
ulOutBufSize, ULONG ullnBufSize, ULONG 
ulTimeOut) 


PARAMETERS 

pszPipeName - input 

A pointer to a buffer containing a null-terminated pipe name. The 
pipe name must have the \PIPE\ prefix, and must conform to the file 
system naming conventions. 

phPipe - output 

The address of an HPIPE that will receive the handle of the newly cre- 
ated pipe. 

ulOpenMode - input 

Bitwise OR the following open mode options (the default is in italics): 
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Constant 
Write-through options: 
NP_WRITEBEHIND 0x0000 


NP_NOWRITEBEHIND 0x4000 


Inherit options: 


NP_INHERIT 0x0000 
NP_NOINHERIT 0x0080 


Duplexing options: 
NP_ACCESS_INBOUND 0x0000 


NP_ACCESS_OUTBOUND 0x0001 


NP_ACCESS_ DUPLEX 0x0002 


ulPipeMode - input 


Description 


For remote connections the data 
written to the pipe should be buffered 
before being sent. 


This pipe will not be buffered over 
remote connections. 


The pipe handle will be inherited by 
child processes. 


The pipe handle will remain private 
to the calling process. 


The pipe is a half-duplex inbound 
pipe (to server). 


The pipe is a half-duplex outbound 
pipe (to clients). 


The pipe is a full-duplex 
inbound/outbound pipe. 


Bitwise OR the following options to set the desired pipe modes (the de- 


fault is in italics): 


Constant 

Blocking options: 

NP_WAIT 0x0000 
NP_NOWAIT 0x8000 


Description 


Create a blocking mode pipe. 
DosRead will block until data is read. 
DosWrite will block until all data is 
written. DosConnectNPipe will block 
until a connection is made. 


Create a nonblocking pipe. DosRead 
returns immediately with a code of 
ERROR_NO_DATA if no data is 
available. DosWrite returns 
immediately if there’s not enough 


Pipe type: 

NP_TYPE_BYTE 0x0000 
NP_TYPE_MESSAGE 0x0400 
Read mode: 

NP_READMODE_BYTE 0x0000 


NP_READMODE._ MESSAGE 0x0100 


Instance count: 


NP_UNLIMITED_INSTANCES — -l 


0 
0 < value < 255 


ulOutBufSize - input 
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buffer space available to write the 
data, otherwise it writes all data and 
returns. DosConnectNPipe will place 
the pipe into the listening state and 
return immediately. 


Create a byte pipe. Data will be 
written as an unformatted stream of 
bytes. 


Create a message pipe. Data will be 
written as a block of information and 
will be prefixed with a system-supplied 
two-byte header that contains the 
length of the message. 


The pipe will be read as an 
unformatted stream of bytes. 


The pipe will be read as a message 
block. DosRead automatically strips 
the system-supplied header. Byte pipes 
cannot be read as message blocks. 


Unlimited instances of the pipe can 
be created. 


Reserved. 


The number of instances is limited to 
the specified value. 


How many bytes the system should allocate for the outbound buffer. 
The maximum size allowed is 65535, however, the maximum that will 


actually be allocated is 65512. 
ullnBufSize - input 


How many bytes the system should allocate for the inbound buffer. 
The maximum size allowed is 65535, however, the maximum that will 


actually be allocated is 65512. 
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ulTimeOut - input 

The default time-out value, in milliseconds, for DosWaitNPipe. If zero 
is specified, then the default is set to 50 milliseconds. This value can 
only be set when creating the first instance of the pipe. 


RETURNS 

0 NO_ERROR 84 ERROR OUT _OF_ 
STRUCTURES 

3 ERROR PATH NOT_FOUND 87 ERROR INVALID _ 
PARAMETER 

8 ERROR NOT ENOUGH __ 231 ERROR PIPE BUSY 

MEMORY 

OTHER INFO 

Include file: bsedos.h Define: INCL. _DOSNMPIPES 

Ordinal: 243 DLL: DOSCALLS 

SEE ALSO 


DosCallNPipe -231, DosClose -220, DosConnectNPipe -234, 
DosDisConnectNPipe -239, DosOpen -223, DosPeekNPipe -240, 
DosQueryNPHsState -242, DosQueryNPipelInfo -244, DosRead -225, 
DosSetNPHState -247, DosSetNPipeSem -249, DosTransactNPipe -251, 
DosWrite -227 


NOTES 


The write-through option is checked only for remote connections. 

Secondary servers can make this call to create and manage addi- 
tional instances of the same pipe. 

For remote named pipes, the server process should not specify its 
computer name as part of the pipe name, otherwise ERROR_PATH_ 
NOT_FOUND is returned. Only clients need the computer name for 
connecting (see DosOpen pg. 223) to remote named pipes. 


RESTRICTIONS/WARNINGS 


@ DosConnectNPipe must be called before any client processes can 
connect to the pipe. 
If an invalid path is given (such as omitting the \PIPE\ prefix) , ER- 
ROR PATH NOT_FOUND is returned. 
If the system cannot allocate the requested pipe buffers or internal 
data structures, then ERROR NOT _ENOUGH_MEMORY is returned. 
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If incorrect mode values are specified, the specified buffer sizes are 
too large, or the pipe is a byte pipe and the read mode is set to mes- 
sage-read mode, then ERROR_INVALID_PARAMETER is returned. 





@ DosDisConnectNPipe Named Pipes 


Acknowledges the closing of a pipe by a client process. 


SYNTAX 
APIRET DosDisConnectNPipe (HPIPE hPipe) 


PARAMETERS 
hPipe - input 
The handle of the pipe to disconnect. 


RETURNS 


0 NO_ERROR 230 ERROR_BAD_PIPE 
109 ERROR_BROKEN_ PIPE 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSNMPIPES 
Ordinal: 242 DLL: DOSCALLS 


SEE ALSO 


DosClose -220, DosConnectNPipe -234, DosCreateNPipe -235, 
DosDisConnectNPipe -239 


NOTES 


This call is used to acknowledge that a client process has closed a named 
pipe handle. The pipe will not be accessible by a client process until the 
server calls DosDisConnectNPipe followed by DosConnectNPipe. If a 
client process issues this call, ERROR_BAD_ PIPE is returned. 

If the server process attempts to read a pipe closed by the client 
process then NO_ERROR is returned and wilBytesRead is zero. If the 
server attempts to write to the pipe, ERROR_BROKEN_PIPE is returned. 

If the server disconnects the pipe before a client closes it, the pipe 
is forced closed, the client’s pipe handle is invalidated, and the client 
receives an error on its next pipe operation. Any data still in the pipe 
will be lost. The client must still issue a DosClose before the resources 
for the pipe instance are freed. 
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RESTRICTIONS/WARNINGS 


@ If the server process disconnects a pipe that has data in it, the data 
will be lost and not accessible for reading by the client process. 





DosPeekNPipe Named Pipes 


Examines the data in a named pipe without removing it from the pipe. 


SYNTAX 


APIRET DosPeekNPipe (HPIPE hpPipe, PVOID pPeekBuf, ULONG 
ulPeekBufLen, PULONG pulBytesRead, PAV- 
AILDATA pByitesAvail, PULONG pulPipeState) 


PARAMETERS 

hpPipe - input 

The handle of the named pipe to peek. 

pPeekBuf - output 

A pointer to a buffer that will receive the examined data. 
ulPeekBufLen - input 

The number of bytes to read into pPeekBuf. 

pulBytesRead - output 

A pointer to a ULONG that will receive the actual number of bytes 
read. 

pBytesAvail - output 

A pointer to an AVAILDATA structure (see pg. 254). The structure 
contains the total number of bytes in the pipe and the number of bytes 
of the current message. 

pulPipeState - output 

A pointer to a ULONG containing the state of the named pipe. 


Constant Description 


NP_STATE_DISCONNECTED 1 The pipe is disconnected. This state 
occurs immediately after the pipe is 
created (DosCreateNPipe), and 
immediately after the pipe is 
disconnected (DosDisConnectNPipe), 
or if the server process dies. 


NP_STATE_LISTENING 2 The server is in the listening state 
(DosConnectNPipe). 
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NP_STATE_ CONNECTED 3 The pipe handle is connected. The 
pipe has been successfully connected 
to by aclient process (if called by the 
server), or the pipe is connected to 
the client process (if called by the 
client). 


NP_STATE_CLOSING 4 The pipe is closed. The pipe handle 
(and any duplicates) have been closed 
by the client process, but has not been 
disconnected by the server. This also 
occurs if the server closes the pipe. 


RETURNS 
0 NO_ERROR 230 ERROR _BAD_ PIPE 
6 ERROR INVALID _ 231 ERROR _PIPE_ BUSY 
HANDLE 
109 ERROR_BROKEN _ 233 ERROR_PIPE NOT_ 
PIPE CONNECTED 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSNMPIPES 
Ordinal: 244 DLL: DOSCALLS 
SEE ALSO 


DosClose -220, DosConnectNPipe -234, DosCreateNPipe -235, 
DosDisConnectNPipe -239, DosOpen -223 


NOTES 


This call may be issued by either the client or the server process. 

If this call is issued by a server and a connected client closes its 
pipe handle, a pipe state of NP_STATE_DISCONNECTED will be re- 
turned until the server acknowledges the close, in which case a state of 
NP_STATE_CLOSING will be returned. 

If the call is made by a client process and the server has discon- 
nected the pipe, a pipe state of NP_STATE_DISCONNECTED is re- 
turned. If the server closed the pipe, but did not disconnect the pipe 
first, a pipe state of NP_STATE_CONNECTED will be returned. 

This call never blocks, even if the pipe is a blocking pipe. If the 
pipe cannot be accessed immediately, then ERROR_PIPE_BUSY is re- 
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turned. This may occur if another thread is reading the pipe or writing 
to the pipe at the moment the call is made. 

The call only returns the information that was in the pipe at the 
moment the pipe was peeked. Therefore, it may be that only a part of 
a message or byte stream will be returned. 





DosQueryNPHState Named Pipes 


Returns handle-specific information for named pipes. 


SYNTAX 

APIRET DosQueryNPHState (HPIPE hpPipe, PULONG 
pulPipeHandleState) 

PARAMETERS 


hpPipe - input 

The handle of the named pipe to query. 

pulPipeHandleState - output 

The address of a ULONG to receive the state of the named pipe han- 
dle. 


Constant Description 

Blocking options: 

NP_WAIT 0x0000 This end of the pipe is in blocking 
mode. 


DosRead will block until data is read. 
DosWrite will block until all data is 
written. DosConnectNPipe will block 
until a connection is made. 


NP_NOWAIT 0x8000 This end of the pipe is in nonblocking 
mode. DosRead returns immediately 
with ERROR_NO_DATA if no data is 
available. DosWrite returns 
immediately if there’s not enough 
buffer space available to write the 
data, otherwise it writes all data and 
returns. DosConnectNPipe will place 
the pipe into the listening state and 
return immediately. 
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Handle end: 

NP_END_CLIENT 0x0000 The handle is for the client end of the 
pipe. 

NP_END_SERVER 0x4000 The handle is for the server end of 
the pipe. 

Pipe type: 

NP_TYPE_BYTE 0x0000 The pipe is a byte pipe. Data is written 
as an unformatted stream of bytes. 

NP_TYPE_MESSAGE 0x0400 The pipe is a message pipe. Data is 
written as a block of information and 
is prefixed with a system-supplied two- 
byte header that contains the length 
of the message. 

Read mode: 

NP_READMODE_BYTE Q0x0000 This end of the pipe is read as an 


unformatted stream of bytes. 


NP_READMODE_MESSAGE 0x0100 This end of the pipe is read in 
message blocks. DosRead 
automatically strips the system- 
supplied header. Byte pipes cannot be 
read in message-read mode. 


Instance count: 


NP_UNLIMITED_INSTANCES -1 Unlimited instances of the pipe can 


be created. 
0 Reserved. 
Q < value < 255 The number of instances is limited to 


the specified value. 


RETURNS 

0 NO_ERROR 231 ERROR BAD PIPE 

6 ERROR_INVALID_HANDLE 233 ERROR PIPE NOT_ 
CONNECTED 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSNMPIPES 


Ordinal: 245 DLL: DOSCALLS 


244 


0S/2® Warp Control Program API 


SEE ALSO 


DosCreateNPipe -235, DosOpen -223, DosQueryNPipeInfo -244, 
DosQueryNPipeSemState -245, DosSetNPHState -247, 
DosSetNPipeSem -249 


NOTES 


Although the pipe type and maximum number of pipe instances can- 
not change from their original values, all the other values can. This call 
will return the values that were set at the moment the call was issued. 

If an invalid pipe handle or a closed pipe handle is specified for 
hpPipe, then ERROR_INVALID_HANDLE is returned. 

If the call is issued by a client process on a pipe handle that is 
no longer connected, then ERROR_PIPE_NOT_CONNECTED is re- 
turned. 





DosQueryNPipelnfo Named Pipes 


Returns static information about a named pipe. 


SYNTAX 


APIRET DosQueryNPipelInfo (HPIPE hpPipe, ULONG ul/nfoLevel, 
PVOID plnfoBuffer, ULONG 
ullnfoBufferSize) 


PARAMETERS 

hpPipe - input 

The handle of the named pipe whose static information is to be 
queried. 

ullnfoLevel - input 

The level of information to be retrieved. Must be either | or 2. 
plnfoBuffer - output 

A pointer to a buffer that will contain either: For level 1, a sequence of 
PIPEINFO structures (pg. 254); for level 2, a unique 2-byte identifier 
of the client. The identifier equates to the key value that was specified 
for DosSetNPipeSem. 

ullnfoBufferSize - input 

The size, in bytes, of the buffer pointed to by plnfoBuffer. 
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RETURNS 
0 NO_ERROR 124 ERROR INVALID LEVEL 
6 ERROR INVALID _ 230 ERROR BAD PIPE 

HANDLE 

111 ERROR BUFFER OVERFLOW 

OTHER INFO 

Include file: bsedos.h Define: INCL DOSNMPIPES 

Ordinal: 248 DLL: DOSCALLS 

SEE ALSO 


DosCreateNPipe -235, DosQueryNPHState -242, 
DosQueryNPipeSemState -245, DosSetNPHState -247, 
DosSetNPipeSem -249 


NOTES 


If the buffer specified in plnfoBuffer is too small to receive all the data, 
then the buffer is filled with as much data as possible and ERROR_ 
BUFFER OVERFLOW is returned. 

If level 1 information is requested, and the length of the pipe 
name is greater than 255 bytes, then a length of zero is returned in the 
uchPipeNameLength field. However, the full name is still returned in the 
achPipeName field. 

If a value other than 1 or 2 is specified for ul/nfoLevel, then ER- 
ROR_INVALID_LEVEL is returned. 

If the handle specified is not a named pipe handle or it’s a closed 
named pipe handle, then ERROR_INVALID_HANDLE is returned. 





DosQueryNPipeSemState Named Pipes 


Returns information concerning the named pipes a semaphore is at- 
tached to. 


SYNTAX 


APIRET DosQueryNPipeSemState (HSEM hsemSemHandle, 
PPIPESEMSTATE pSemStateBuf, 
ULONG uwllnfoBufLen) 
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PARAMETERS 


hsemSemHandle - input 

The handle of the shared event or muxwait semaphore that is attached 
to one or more named pipes. 

pSemStateBuf - output 

A pointer to a buffer that will receive the PIPESEMSTATE records for 
each attached named pipe. See the PIPESEMSTATE structure on page 
20, 

ullnfoBufLen - input 

The size, in bytes, of the buffer pointed to by pSemStateBuf. See the 
Notes section regarding sizing information. 


RETURNS 

0 NO_ERROR 111 ERROR BUFFER OVERFLOW 
87 ERROR INVALID PARAMETER 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSNMPIPES 
Ordinal: 249 DLL: DOSCALLS 

SEE ALSO 


DosCreateNPipe -235, DosQueryNPHState -242, 
DosQueryNPipelInfo -244, DosSetNPHState -247 


NOTES 


This call returns status information on local named pipes that are at- 
tached by the specified shared event or muxwait semaphore. 

Since the semaphore specified must be a shared semaphore, the 
records returned may refer to named pipes that are not accessed by 
the calling process. Therefore, it is a good idea to develop a conven- 
tion for the key values that are assigned when the DosSetNPipeSem 
call is made. This way the caller will know if the pipe is of interest. 

If the semaphore is attached to multiple named pipes then the key 
value returned can be used to determine which named pipe has data 
to read, or which has write space available. 

The size specified should be a minimum of (((3 * NUM_OF_ 
PIPES) + 1) * size of (PIPESEMSTATE) ) for full-duplex pipes. ‘This size 
calculation is necessary since there can be up to three PIPESEMSTATE 
records (one for NPSS_RDATA, one for NPSS_WSPACE, and one for 
NPSS_CLOSE) returned per full-duplex pipe and two per half-duplex 
pipe. The additional PIPESEMSTATE record is to hold the NPSS_EOI 
record which is returned for the final record in the buffer. 
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@® DosResetBuffer Named Pipes 





Blocks the calling thread until all written data has been read at the 
other end of the pipe. 


SYNTAX 
APIRET DosResetBuffer (HFILE h/PipeHandle) 


PARAMETERS 

hfPipeHandle - input 

The handle of the pipe to block on. For named pipes, the pipe handle 
must be cast to an HFILE. 


RETURNS 

0 NO_ERROR 5 ERROR ACCESS DENIED 

2 ERROR FILE NOT_FOUND 6 ERROR_INVALID HANDLE 
OTHER INFO 

Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 254 DLL: DOSCALLS 

SEE ALSO 


DosOpen -223, DosWrite -227 


NOTES 

This call is issued after writing data to a named pipe. It is used to syn- 
chronize read and write dialogs. The call will block the calling thread 
until the data is read at the other end of the pipe. 





@® DosSetNPHState Named Pipes 


Sets the blocking and read modes of a named pipe handle. 


SYNTAX 
APIRET DosSetNPHState (HPIPE hpPipe, ULONG wlPipeHandleModes) 


PARAMETERS 
hpPipe - input 
The named pipe handle whose modes will be changed. 
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ulPipeHandleModes - input 


The following mode options may be selected (the default is in italics): 


Constant 
Blocking options: 
NP_WAIT 


NP_NOWAIT 


Read mode: 


NP_READMODE_BYTE 


NP_READMODE_MESSAGE 


RETURNS 


0 NO_ERROR 
87 ERROR_INVALID_ 

PARAMETER 
230 ERROR _BAD_ PIPE 


0x0000 


0x8000 


0x0000 


0x0100 


Description 


Set the pipe handle to blocking 
mode pipe. 


DosRead will block until data is 
read. DosWrite will block until all 
data is written. DosConnectNPipe 
will block until a connection is 
made. 


Set the pipe handle to nonblocking 
mode. DosRead returns 
immediately with ERROR_NO_ 
DATA if no data is available. 
DosWrite returns immediately if 
there’s not enough buffer space 
available to write the data, 
otherwise it writes all data and 
returns. DosConnectNPipe will 
place the pipe into the listening 
state and return immediately. 


The pipe will be read as an 
unformatted stream of bytes. 


The pipe will be read as a message 
block. DosRead automatically strips 
the system-supplied header. Byte 
pipes cannot be read as message 
blocks. 


231 ERROR_PIPE_ BUSY 
233 ERROR_PIPE_ NOT_ 


CONNECTED 
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OTHER INFO 

Include file: bsedos.h Define: INCL. DOSNMPIPES 
Ordinal: 250 DLL: DOSCALLS 

SEE ALSO 


DosCallNPipe -231, DosConnectNPipe -234, DosCreateNPipe -235, 
DosQueryNPHsState -242, DosRead -225, DosResetBuffer -247, 
DosTransactNPipe -251, DosWrite -227 


NOTES 


Both the blocking mode and read mode must be specified. Any previ- 
ous handle settings will be overridden. 


RESTRICTIONS/WARNINGS 


@ Byte pipes can only be read in byte-read mode, and any attempt to 
set a byte pipe to message-read mode will return ERROR_IN- 
VALID_PARAMETER. 

@ The blocking mode of a pipe handle cannot be changed to non- 
blocking mode by another thread if there is already a thread 
blocked on an I/O request for the same handle. It should be noted 
that the server process has a different pipe handle than the client 
process. 





DosSetNPipeSem Named Pipes 


Attaches a shared event or muxwait semaphore to a named pipe 
handle. 


SYNTAX 


APIRET DosSetNPipeSem (HPIPE hpPipe, HSEM hsemSemHandle, 
ULONG wlKey Value) 


PARAMETERS 

hpPipe - input 

The handle of the pipe to which the semaphore will be attached. The 
handle may be a client or server handle. 

hsemSemHandle - input 

The handle of the shared event or muxwait semaphore that will be at- 
tached to the pipe. 
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ulKeyValue - input 
The value of a key that uniquely identifies the pipe handle. This maxi- 
mum key value is 65535. 


RETURNS 

0 NO_ERROR 187 ERROR SEM NOT_FOUND 

1 ERROR_ INVALID _ 230 ERROR BAD PIPE 
FUNCTION 

6 ERROR _ INVALID _ 233. ERROR PIPE NOT_ 
HANDLE CONNECTED 

87 ERROR INVALID PARAMETER 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSNMPIPES 

Ordinal: 25] DLL: DOSCALLS 

SEE ALSO 


DosConnectNPipe -234, DosCreateNPipe -235, 
DosQueryNPHState -242, DosQueryNPipelInfo -244, 
DosQueryNPipeSemState -245, DosSetNPHState -247, 
DosWaitEventSem -312, DosWaitMuxWaitSem -331 


NOTES 


The event semaphore that is attached to a pipe will be posted when- 
ever data has been written to or read from the pipe. The pipe may ex- 
ist remotely, but the semaphore can only be attached to the handle be- 
longing to the calling process. See DosWaitEventSem, page 331, and 
DosWaitMuxWaitSem, page 334, for more information on semaphore 
blocking. 

Since the same semaphore may be attached to multiple pipes, the 
key value should be used to uniquely identify each pipe handle. This 
allows a thread that was blocked on the semaphore to determine which 
pipe has data or write space available. 

If an attempt is made to attach the semaphore to a remote pipe 
handle, ERROR_INVALID_FUNCTION is returned. 

If the semaphore specified does not exist, then ERROR_SEM_ 
NOT_FOUND is returned. If the pipe handle specified is not valid, 
then ERROR INVALID HANDLE is returned. 

If the semaphore specified is not a shared semaphore, then ER- 
ROR_WRONG_TYPE is returned. The shared semaphore may be 
named or unnamed. 
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If the key value specified is greater than 65535, then ERROR_IN- 
VALID PARAMETER is returned. 

If the specified pipe handle already has a semaphore attached, it is 
replaced with the new semaphore. 





DosTransactNPipe Named Pipes 


Writes to a full-duplex message pipe, and then reads from it. 


SYNTAX 


APIRET DosTransactNPipe(HPIPE hpPipe, PVOID pOutBuffer, ULONG 
ulOutBufferLen, PVOID plnBuffer, ULONG 
ullnBufferLen, PULONG pulBytesRead) 


PARAMETERS 

hpPipe - input 

The handle of the full-duplex message pipe to execute the transaction 
on. The handle must be in message-read mode. 

pOutBuffer - input 

A pointer to a buffer containing the data to be sent across the pipe. 
ulOutBufferLen - input 

The number of bytes to be sent, up to 65535. 

plnBuffer - output 

A pointer to a buffer that will receive the data that was read from the 
pipe. 

ullnBufferLen - input 

The size, in bytes up to 65535, of the buffer pointed to by plnBuffer. 
pulBytesRead - output 

The address of a ULONG to receive the number of bytes read into 


plnBuffer. 


RETURNS 
0 NO_ERROR 231 ERROR_PIPE_BUSY 
1 ERROR_INVALID_ 233: ERROR_PIPE_NOT_ 
FUNCTION CONNECTED 


11 ERROR_BAD_FORMAT 234 ERROR MORE DATA 
230 ERROR_BAD_ PIPE 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSNMPIPES 
Ordinal: pon DLL: DOSCALLS 
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SEE ALSO 


DosClose -220, DosCreateNPipe -235, DosCallNPipe -231, DosConnect- 
NPipe -234, DosPeekNPipe -240, DosRead -225, DosSetNPHState -247 


NOTES 


The current blocking mode of the pipe handle is irrelevant. Dos- 
TransactNPipe will block until it can read a response from the pipe. 

If the buffer pointed to by plnBuffer is too small to contain the re- 
sponse message, then ERROR_MORE_DATA is returned. A subse- 
quent call to DosTransactNPipe will return ERROR_PIPE_BUSY. 

If the target pipe handle refers to either STDIN (0), STDOUT (1), 
or STDERR (2), then ERROR_INVALID_ FUNCTION is returned. If the 
target pipe handle references a byte pipe, then ERROR_BAD_FORMAT 
is returned. 

If the pipe has been disconnected by the server (see DosDis- 
ConnectNPipe), then ERROR_PIPE_NOT_CONNECTED is returned. 


RESTRICTIONS/WARNINGS 


@ [he outbound data buffer must not cross a 64k boundary, and the 
message must be aligned on a doubleword boundary. 

@ This call will only work correctly on full-duplex message pipes that 
are in message-read mode. If the pipe is not a full-duplex message 
pipe, the call returns ERROR_BAD_FORMAT. However, if the call is 
not in message-read mode, no error is returned, but the response 
message is corrupted. 

@ If the call is issued on a closed pipe (the server called DosClose), 
then odd behavior may occur. 

@ If the pipe already has data to be read when this call is issued, the 
call will return immediately with that data and place the transaction 
out of synch since the read portion of the transaction will be ex- 
pecting a response for its request and receive old data instead. If the 
pipe has outbound data already in it when this call is issued, then 
the data read by the other end of the pipe, will be out of synch with 
the transaction. The synchronization problem occurs because the 
data already outbound will be read first by the other end of the pipe, 
and the actual outbound transaction data will not be processed un- 
til the other end of the pipe reads the pipe again. It is important to 
note that this synchronization problem occurs only when the pipe 
has data in it that was generated by prior calls to DosWrite. If there 
is leftover data in the pipe due to a DosTransactNPipe call that had 
too small a buffer to retrieve all of the data, then ERROR_ PIPE_ 
BUSY is returned. 
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@ DosWaitNPipe Named Pipes 


Waits for an instance of a named pipe to become available. 


SYNTAX 
APIRET DosWaitNPipe(PSZ pszPipeName, ULONG ulTimeOut) 


PARAMETERS 

pszPipeName - input 

The name of the pipe to wait for. 

ulTimeOut - input 

The timeout, in milliseconds, before returning if no pipe instance be- 
comes available. The following values may be specified instead: 


Constant Description 


NP_DEFAULIT_WAIT 0 The timeout is set to the value specified 
for timeout when the pipe was created 
(see DosCreateNPipe pg. 235). 


NP_INDEFINITE_WAIT -1 The call will wait indefinitely for a pipe 
instance to become available. 


RETURNS 

0 NO_ERROR 11 ERROR_BAD_FORMAT 
1 ERROR_INVALID_FUNCTION 95 ERROR_INTERRUPT 
2 ERROR_FILE_NOT_FOUND 231 ERROR_PIPE_BUSY 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSNMPIPES 
Ordinal: 253 DLL: DOSCALLS 

SEE ALSO 


DosConnectNPipe -234, DosCreateNPipe -235, DosOpen -223, 
DosQueryNPHInfo -244, DosSetPriority -280 


NOTES 


This call should only be used if DosOpen returns ERROR_PIPE_BUSY. 
If the timeout value of the call is exceeded, then ERROR_ 
PIPE BUSY is returned. 
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After DosWaitNPipe returns with the successful return code, the 
client process should issue DosOpen again. If multiple clients are wait- 
ing for a pipe instance from the same pipe, then the client with the 
highest priority will be given the pipe instance first. If all the clients 
waiting for the pipe instance have the same priority, then the client 
waiting the longest will receive the pipe instance. See DosSetPriority, 
page 280, for changing the priority of a thread. 


Pipes Structures 





cbpipe (USHORT) 0 
The total number of bytes in the pipe, including any system-added message headers. 
cbmessage (USHORT) 2 


The number of bytes in the current message, or zero if it’s a byte pipe. 


Used by: DosPeekNPipe -240 





cbOut (USHORT) 0 
The actual size of the outbound buffer. 

cbIn (USHORT) 2 
The actual size of the inbound buffer. 

cbMaxInst (BYTE) 4 
The maximum number of simultaneously supported pipe instances. 

cbCurInst (BYTE) 5 
The current number of pipe instances. 

cbName (BYTE) 6 
The length of the pipe name, in bytes. 

szName[1] (CHAR) 7 


The null-terminated name of the pipe (including the computer name if it is a remote pipe 
and the query is being made by a client process). 
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Used by: DosQueryNPipelInfo -244 





fStatus (BYTE) 0 
The status of the pipe. May be one of the following values: 
Constant Description 
NPSS_EOI 0 End of information buffer. There are no more PIPESEM- 
STATE records, and the remaining fields are undefined. 
NPSS_RDATA 1 There is data in the pipe to read. 
NPSS_WSPACE 2 There is space available to write data. 
NPSS_CLOSE 3 The pipe is closed. 
fFlag (BYTE) 1 
Additional pipe state flag: 
Constant Description 
NPSS_WAIT 1 There is a blocked thread for this pipe on the other end. 
usKey (USHORT) | Z 
A user key value. This is the value that was specified for ulKeyValue when DosSetNPipeSem 
was Called. 
usAvail (USHORT) 4 


If {Status equals NPSS_RDATA then it contains the number of bytes of data that may be read 
from the pipe. If fStatus equals NPSS_WSPACE then it contains the number of bytes of write 
space available. 


Used by: DosQueryNPipeSemState -245 





I 
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S/2 code is organized at two levels: processes and threads. A pro- 

gram that is loaded into memory and is ready for execution is a 
process. Processes only denote the organization of resources in OS/2. 
Threads are the unit of execution in OS/2. Every program executes in 
its Own process with its own linear address space, file handles, pipe 
handles, queue handles, and so on. So, while many programs may be 
running simultaneously on the same system, each is guaranteed mem- 
ory and file handles that cannot be accessed or corrupted by other 
programs. OS/2 automatically handles the context switching that must 
occur when the scheduler switches execution from one process to an- 
other. Process context switching is not as fast as thread context switch- 
ing and requires more RAM as well. Child (related) processes may be 
started with DosExecPgm. 

Threads are the units of execution that make up a process. Each 
thread receives its own stack and register context, but shares address 
space, file handles, pipe handles, queue handles, and more with all 
other threads of the process they belong to. Every process has at least 
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one thread, often referred to as the main thread, which always has a 
thread ID of 1. If thread 1 terminates, then the entire process termi- 
nates. Typically, threads are started to do jobs that may cause the in- 
terface to be suspended while a task is performed. For example, a data- 
base search could take some time to process and, therefore, could be 
started as a separate thread so that the user could do other things with 
the application while that task is being performed. Often, some syn- 
chronization of threads must be performed so that execution will pro- 
ceed in the correct order. For example, a thread (say thread 3) may be 
waiting for data to come across a pipe while another thread (thread 4) 
writes the information to a file. Obviously, we don’t want thread 4 to do 
anything until thread 3 gets the data. To handle these situations, OS/2 
provides a method of synchronization known as semaphores (see 
Chapter 13, Semaphores, page 302) that can be used to ensure that the 
thread will block until the expected event has occurred. 

Threads are really just functions that execute asynchronously. Any 
function invoked from within a thread runs from the context of that 
thread. Consequently, if you have functions that will be called from 
more than one thread, it is very important to write them reentrant or 
with semaphore control. For example, thread A does not change the 
value of a global variable that thread B intends to manipulate as well. 
It is a bad idea to assume that one thread will have finished doing 
something before another thread does something. OS/2 can and will 
dynamically adjust the priority of threads based on certain conditions 
which can cause the flow of execution to be very different than what 
you expect. 

Threads can be started using DosCreateThread. However, if the 
thread is going to call C or C++ library functions, it should be started 
using _beginthread, which is not ANSI standard and may not be sup- 
ported by all compilers. 


Restrictions and Warnings 


@ There is a system-wide limit of 4095 processes and 4095 threads. 

@ Process and thread IDs are reused by the system. 

@ Threads calling Presentation Manager functions other than Win- 
PostMsg must have a Presentation Manager message queue running 
on the thread. 
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Process Level Functions 





DosEnterCritSec causes thread switching for the current process to be 
disabled (pg. 258). 

DosExecPgm starts a synchronous or asynchronous child process that 
is the same application type as the calling process (pg. 259). 
DosExitCritSec resumes thread switching for the current process 
(pg. 258). 

DosExitList maintains a list of routines to execute when the process 
terminates (pg. 264). 

DosKillProcess sends a kill process signal exception to the target 
process (pg. 267). 

DosWaitChild causes the current process to suspend until the specified 
asynchronous process terminates (pg. 269). 





DosEnterCritSec Process/Thread Management 


Causes thread switching for the current process to be disabled. 


SYNTAX 
APIRET DosEnterCritSec( ) 


PARAMETERS 


None 


RETURNS 


0 NO_ERROR 309 ERROR_INVALID_THREADID 
484 ERROR_CRITSEC_OVERFLOW 


OTHER INFO 


Include file: bsedos.h Define: INCL. _DOSPROCESS 
Ordinal: 232 DLL: DOSCALLS 


SEE ALSO 
DosExitCritSec -263, DosSetPriority -280 
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NOTES 


The current thread of the process will continue to compete for proces- 
sor time with all other processes, however, all other threads of the cur- 
rent process will be suspended until DosExitCritSec is encountered. 

Threads can also control the flow of execution by setting the pri- 
ority and by using semaphores. DosEnterCritSec should only be used 
for small sections of code that must run while no other thread in the 
process is running. 

If the process receives a signal, thread 1 (main thread) will begin 
execution to handle the processing of the signal even though it may 
not be the thread that executed the DosEnterCritSec. 

Each call to DosEnterCritSec increments a counter, and is decre- 
mented by DosExitCritSec. The other threads will not begin normal 
execution until the count reaches zero. The count is stored in a word, 
and if an overflow occurs, then an ERROR CRITSEC_OVERFLOW 
will be returned and the count will remain unchanged. 


RESTRICTIONS/WARNINGS 


@ Critical sections are very dangerous when calls are made to func- 
tions where the internals of those functions are not known. This is 
due to the fact that functions may be requesting resources (such as 
semaphores) that will never become available because all other 
threads in the process are blocked, and therefore cannot release 
those resources. In this case, the application will deadlock. If possi- 
ble, avoid making any function calls while inside of a critical section. 
If the calling thread is attempting to enter a critical section while 
within an exception handler or a signal handler, ERROR_IN- 
VALID THREADID will be returned. The same is true if a DLL rou- 
tine attempts to illegally enter a critical section. 

While the main thread is doing its signal processing, it should not 
attempt to access the resource(s) being protected by the critical 
section. 

@ A thread that is in a critical section should not attempt to execute 

any calls to functions that are dynamically linked. 





DosExecPgm Process Management 


Starts programs of the same type as a child process. 
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SYNTAX 


APIRET DosExecPgm(PCHAR pOljNameBuf, LONG lObiNameBufLen, 
ULONG wilkxeclags, PSZ pszArguments, PSZ 
pszEnvironmentStrings, PRESULTCODES 
pResultCodes, PSZ pszProgramName) 


PARAMETERS 


pObjNameBuf - output 

The address of the buffer to contain the name of the procedure that 
caused the application to fail. ‘This is primarily used for debugging ap- 
plications and should be set to NULL otherwise. 

1O0bj;NameBufLen - input 

The length of pObjNameBuf, in bytes. 

ulExecFlags - input 

Specify one of the following options: 


Constant Description 


EXEC_SYNC Q Run the process synchronously. The 
RESULTCODES structure is returned in 
its entirety. 


EXEC_ASYNC 1 Run the process asynchronously. The 
process ID is returned in the codeTerminate 
member of the RESULT'CODES structure. 
The codeResult member is not returned. 


EXEC_ASYNCRESULT 2 Run the process asynchronously. The 
process ID is returned in the codeTerminate 
member of the RESULTCODES structure. 
The result code can be examined via 


DosWaitChild. 

EXEC_TRACE 3 Same as EXEC_ASYNCRESULT except 
the program is set up for debugging (for 
debuggers only). 

EXEC_BACKGROUND 4 Run the process asynchronously and as a 


detached process. The detached process 
runs independently and is not affected by 
the termination of the parent process. 
Detached processes cannot process any 
keyboard input or screen output (except 
via VioPopup) and should not issue any 
VIO, MOU, or KBD calls. 
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EXEC_LOAD 5 The process is loaded and made ready to 
execute, however, it is not started until 
another process performs a system service 
that causes the loaded process to thaw. 


EXEC _ASYNCRESULTDB 6 Same as EXEC_TRACE, except the 
program and its children are set up for 
debugging so that detached and 
synchronous processes can be debugged. 


pszArguments - input 

A pointer to a buffer containing argument strings. Each argument ex- 
cept the first argument should be separated by spaces. The first argu- 
ment should be null-terminated, and the last argument should be dou- 
ble null-terminated. Strings containing spaces should be enclosed in 
quotes to be treated as one argument. The first argument should be 
the name of the program to be started as if it were typed on the com- 
mand line. A NULL pointer indicates there are no arguments to be 
passed to the program. An example of formatting this argument in C 
might be: 


sprintf(szBuff, “MYPROG.EXE%Scparm2 \"parm three\”%c”, 0, 0); 


Note that the example explicitly specifies a NULL after the first argu- 
ment and the last argument, and places the string in quotes so that the 
entire argument string will be terminated with a double NULL (ac- 
cording to C language rules). The third parameter is enclosed in 
quotes so that it will be treated as a single argument. 
pszEnvironmentStrings - input 

A pointer to a buffer containing environment settings. Each setting 
string must end in a NULL with an additional NULL appended to the 
end of the last string. ‘The format of an environment setting is: 


EnvVar = Value 
An example of this argument might be: 


sprintf(szBuff, “INCLUDE=D:\C\INCLUDE;D:\MYSTUFF\ INCLUDE; $cTEMP=D: 
\TEMPSc”, 0, 0); 


Note that the example explicitly specifies a NULL after each environ- 
ment setting, and places the string in quotes so that the environment 
is terminated with a double NULL. The system will allocate a maxi- 
mum of 64k for the environment. 
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If NULL is specified for pszEnvironment, then the parent’s environ- 
ment is used. If any environment settings are specified, then none of 
the parent environment is used. 
pResultCodes - output 
The address to receive the RESULTCODES structure. This structure 
contains the process ID or termination code and result code for the 
child process. 
pszProgramName - input 
The name of the program to be started. If just the program name is 
specified, first the current directory is searched and then each path in 
the PATH statement. Alternately, a fully qualified path can be speci- 
fied. This value will be passed as an argument string to the new process 
if pszArguments is NULL. 


RETURNS 


0 NO_ERROR 13. ERROR_INVALID_DATA 

2 ERROR_FILE_ NOT_FOUND 26 ERROR NOT_DOS_DISK 

3 ERROR_PATH_NOT_FOUND 32 ERROR_SHARING_ 

VIOLATION 
4 ERROR_TOO_MANY_ 33 ERROR_LOCK_VIOLATION 
OPEN_FILES 
5 ERROR_ACCESS DENIED 108 ERROR _DRIVE_LOCKED 
8 ERROR_NOT_ENOUGH_ = 190 ERROR_INVALID_ 


MEMORY MODULETYPE 

10 ERROR BAD _ 191 ERROR INVALID EXE _ 
ENVIRONMENT SIGNATURE 

11 ERROR BAD FORMAT 192 ERROR EXE MARKED 

INVALID 

OTHER INFO 

Include file: bsedos.h Define: INCL. DOSPROCESS 

Ordinal: 283 DLL: DOSCALLS 

SEE ALSO 


DosStartSession - 340, DosKillProcess - 267, DosExit - 277, 
DosWaitChild - 269, _execl, _spawnl, system, WinStartA pp 


NOTES 


Processes started without the EXEC_BACKGROUND flag have a 
parent-child process relationship between the calling process and the 
started process. 
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The newly created process receives its own unique linear address 
space. However, the process will inherit all file handles and pipes of the 
parent process with the following restriction: The parent process may 
redirect the standard I/O handles of its child process using 
DosDupHandle. For example, the parent process first creates a read 
pipe using DosCreatePipe and then duplicates the handle as standard 
input. This allows the parent process to write to the pipe handle as if it 
were the standard input of the child process. 

If the ulExechlags parameter is set to either EXEC_TRACE or 
EXEC_ASYNCRESULTDB, then debugging capabilities are enabled 
that will allow DosDebug to perform step and breakpoint debugging. 
For greater debugging flexibility see DosStartSession pg. 340. 

You can test whether a program is detached by issuing a VIO call. 
If there is no VIO popup running, the call will return the error ER- 
ROR_VIO_DETACHED. 


RESTRICTIONS/ WARNINGS 


@ DosExecPgm can only be used to start a process that is of the same 
type as the calling process. Use DosStartSession or WinStartApp to 
start application types that are different than the calling process. 

@ Files opened with the OPEN_FLAGS_NOINHERIT flag are not in- 
herited. 

@ A process started with the ulExecflags parameter set to EXEC_BACK- 
GROUND is treated as a detached process and cannot make any 
VIO, MOU, or KBD calls except while a VIO popup is running. 





DosExitCritSec Process/Thread Management 





Exits a critical section and causes normal thread dispatching to re- 
sume. 


SYNTAX 
APIRET DosExitCritSec () 


PARAMETERS 


None 
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RETURNS 

0 NO_ERROR 309 ERROR _ INVALID THREADID 
485 ERROR CRITSEC_UNDERFLOW 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSPROCESS 
Ordinal: 209 DLL: DOSCALLS 
SEE ALSO 


DosEnterCritSec -258 


NOTES 


This call should be issued only after a critical section has been entered 
for the current thread (using DosEnterCritSec), otherwise an ER- 
ROR CRITSEC_UNDERFLOVW error will be returned. 

Each call to DosEnterCritSec increments a counter, and is decre- 
mented by DosExitCritSec. The other threads will not begin normal 
execution until the count reaches zero. The count is stored in a word, 
and if an underflow occurs, then an ERROR _CRITSEC_UNDER- 
FLOW will be returned and the count will remain at zero. 

If the calling thread is attempting to exit a critical section while 
within an exception handler or a signal handler, ERROR_INVALID_ 
THREADID will be returned. The same is true if a DLL routine at- 
tempts to illegally exit a critical section. 





DosExitList Process Management 


Maintains a list of exit list routines to execute when the process termi- 
nates. 


SYNTAX 

APIRET DosExitList( ULONG wlOrderCode, PFNEXITLIST 
pFunctionAddress) 

PARAMETERS 


ulOrderCode - input 

This parameter is broken up into three sections: first, the high-order 
word, which should be set to zero; second, the low-order byte of the 
low-order word, which should be set to the operation the DosExitList 
should perform. The following operations are supported: 
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Constant Description 

EXLST ADD 1 Add an address to the exit list. 

EXLST_ REMOVE 2 Remove an address from the exit list. 
EXLST_EXIT 3 ‘Transfer execution to the next address in 


the exit list. 


Third, the high-order byte of the low-order word sets the invocation or- 
der of the function. For example, the ul/OrderCode parameter would be 
specified as this for the add operation: (EXLST_ADD | 0x0800). The 
invocation order parameter is only valid when the EXLST_ADD oper- 
ation is being performed, and should be set to zero otherwise. The 
functions in the list are executed in order starting from 0 and working 
up to 255. If the same invocation order is specified more than once, 
then the last one added will be executed first. The following is a list of 
orders used by OS/2 system components: 


Value Component 

0x80 - 0x88 Extended Edition Database Manager 

0x90 - 0x98 Extended Edition Communications Manager 
OxA0O - OxA8 Presentation Manager 

OxBO Keyboard subsystem (KBD) 

0xC0 Video subsystem (VIO) 

OxDO Interprocess communication (IPC) for Queues 


pFunctionAddress - input 
The address of the function is to be either added or removed. 


RETURNS 
0 NO_ERROR 8 ERROR INVALID FUNCTION 
1 ERROR_NOT_ENOUGH_ 13 ERROR INVALID DATA 
MEMORY 
127 ERROR _ PROC _NOT_ 183. ERROR ALREADY EXISTS 
FOUND 
OTHER INFO 
Include file: bsedos.h Define: INCL. DOSPROCESS 


Ordinal: 296 DLL: DOSCALLS 
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SEE ALSO 
atexit, DosExit -277, DosKillThread -273, DosKillProcess - 267 


NOTES 


Exit lists are used to make sure that “loose ends” are cleaned up before 
a process terminates either normally or abnormally. Loose ends can 
mean anything from saving a file to freeing memory or clearing sema- 
phores. This type of processing is especially useful for DLLs where the 
client process could terminate without notice to the DLL. 

All exit list processing occurs on thread 1. Before the system be- 
gins exit list processing, it will first reset the stack (of thread 1) to its 
initial state, and the routines will be executed based on the execution 
order specified, starting from 0. 

The ulTermCode parameter contains a code that indicates why the 
process is terminating. The following termination codes are valid: 


Constant Description 

TC_EXIT 0 Normal termination. 

TC_HARDERROR 1 Process terminated due to a hard error. 
TC_TRAP 2 Atrap occurred for the 16-bit child process. 
TC_KILLPROCESS 3 Unintercepted DosKillProcess. 
TC_EXCEPTION 4 An exception occurred for the 32-bit child 


Process. 


When the system begins exit list processing, system semaphores 
owned by the process are transferred to the thread performing exit list 
processing. This is to prevent deadlock situations where a semaphore 
that was owned by a thread has terminated and the exit routine wants 
to serialize processing with that semaphore. 


RESTRICTIONS/WARNINGS 


@ When a termination routine is finished processing, it must issue a 
DosExitList call with the EXLST_EXIT operation specified so the 
processing can continue to the next routine. Exit list routines 
should be written as small and quick as possible. 

@ All control program functions are valid in exit list processing except 
for DosCreateThread and DosExecPgm. Exit routines cannot call 
other exit routines that are higher in priority; for example, a prior- 
ity OxB routine cannot call a OxA routine. 
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@ All exit routines must be declared using the following prototype: 
VOID APIENTRY Routine (ULONG ulTermCode) 


@ Workplace Shell classes running under the Workplace Shell process 
should not register an exit list routine or load a DLL that registers 
an exit list routine. The Workplace Shell never exits, and if SOM un- 
loads the class, the DLL will not be unloaded. Additionally, the ob- 
jects of that class will not be able to wake up until the Workplace 
Shell traps or the machine is rebooted. 

@ If the function to be added already exists in the exit list, then ER- 
ROR ALREADY EXISTS is returned. 

e If the function to be removed is not in the exit list, then ERROR_ 
PROC_NOT_FOUND is returned. 





DosKillProcess Process Management 





Sends the kill process signal exception to the specified process or 
process tree. 


SYNTAX 
APIRET DosKillProcess(ULONG wlActionCode, PID idProcess) 


PARAMETERS 


ulActionCode - input 
Specify one of the following values: 


Constant Description 


DKP_PROCESSTREE Q Sends an XCPT_SIGNAL_KILLPROC signal 
exception to the specified process and all of 
its child processes. ‘The process must be 
either the current process or a child process 
started using DosExecPgm with the EXEC_ 
ASYNCRESULT flag. After the given process 
is terminated, the child processes will be 
flagged for termination. Even if the parent 
process has terminated, the child processes 
will still be sent an XCPT_SIGNAL__ 
KILLPROC exception signal. 
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DKP_PROCESS 1 Sends an XCPT_SIGNAL_KILLPROC signal 
exception to the specified process even 
though it may not be the current process or a 
child process. Only the specified process will 
be terminated, and no children. 


idProcess - input 
The process to be sent the XCPT_SIGNAL_KILLPROC signal excep- 
tion. 


RETURNS 

0 NO_ERROR 217 ERROR ZOMBIE PROCESS 
13 ERROR INVALID DATA 303 ERROR INVALID PROCID 
162 ERROR SIGNAL _ 305 ERROR NOT DESCENDANT 

PENDING 

OTHER INFO 
Include file: bsedos.h Define: INCL. DOSPROCESS 
Ordinal: 235 DLL: DOSCALLS 
SEE ALSO 


DosExecPegm - 259, DosKillThread -273, DosSetExceptionHandler -38 


NOTES 


A process that is handling this exception should clean itself up (for ex- 
ample, closing open files) before going on with the termination. 

If the exception is not handled the call acts as if one of its own 
threads has issued the call, and all file buffers will be written and any 
open handles will be closed. Any nonsystem-managed buffers (such as 
the buffers created by low-level C library functions) will not be flushed. 

If the parent process of the terminating process calls DosWait- 
Child, it will get the TC_KILLPROCESS termination code. 

The ERROR ZOMBIE PROCESS return code is returned when 
the process has terminated before the parent has issued the DosWait- 
Child call. 


RESTRICTIONS/WARNINGS 


@ It is important to note that an XCPT_SIGNAL_KILLPROC signal 
exception is sent to the target process(es). This does not guarantee 
that the target process will terminate since the target process can 
choose to discard the signal exception. 
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@ DosWaitChild Process/Thread Management 


Causes the current thread to wait until the specified asynchronous 
child process terminates. 


SYNTAX 


APIRET DosWaitChild(ULONG ulActionCode, ULONG ulWaztOpiion, 
PRESULTCODES pResuliCodes, PPID 
pRetProcessID, PID ProcessID) 


PARAMETERS 
ulActionCode - input 
Specify what to wait for: 


Constant Description 


DCWA_PROCESS Q Wait for the child process specified in 
ProcessID to terminate. 


DCWA_PROCESSTREE 1 Wait until the child process specified in 
ProcessID and all of its child processes 
terminate. 


ulWaitOption - input 
Specify one of the following wait options: 


Constant Description 


DCWW_WAIT QO Wait until either the process (if 
DCWA_PROCESS was specified) or process 
tree (if DOWA_PROCESSTREE was specified) 
has ended or there are no child processes 
left. 


DCQWW_NOWAIT 1 Don’t wait for a child process to end; return 
immediately. Use this option if you expect 
that the child process has already terminated 
and you just want its termination and result 
codes. 


pResultCodes - output 
Specify the address of a RESULTCODES structure that will receive 
the termination code and result code of the terminating child process. 
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If the child process does not provide a return code, the system will 
insert a (-1). 

pRetProcessID - output 

Specify the address of a PID to receive the terminating process ID. 
ProcessID - input 

The process ID or the root process ID of a child process tree to wait on. 
A zero indicates that waiting will occur until any child process termi- 
nates. This process may have already terminated. 


RETURNS 
0 NO_ERROR 129 ERROR _CHILD NOT _ 

COMPLETE 

13 ERROR_INVALID_ DATA 184 ERROR NO_CHILD_ 
PROCESS 

128 ERROR WAIT NO_ 303 ERROR_INVALID_ PROCID 

CHILDREN 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSPROCESS 

Ordinal: 280 DLL: DOSCALLS 

SEE ALSO 


DosExecPgm - 259, DosExit - 277, DosWaitThread - 276 


NOTES 


This call waits for the termination of child processes started with the 
EXEC_ASYNCRESULT option in DosExecPgm. If the termination 
process has multiple threads, the code returned in the RESULI- 
CODES structure will be from the thread that issued the DosExit that 
caused the process to end. 

Return codes and termination codes are not returned for 
processes further in the hierarchy than the child process. 

If there are no child processes (or processes that have ended with 
a return code) executing, an error will be returned. 

DosWaitChild will wait on any child process whether it was started 
with the EXEC_ASYNCRESULT flag or not. However, the call will not 
return until a child process with a result code terminates or all child 
processes have terminated. 


Processes and Threads 271 


Thread Level Functions 





DosCreateThread creates an asynchronous thread of execution (pg. 271). 
DosKillThread terminates another thread within the current process 
(pe. 273). 

DosResumeThread causes a thread to resume execution (pg. 274). 
DosSuspendThread suspends execution of a thread (pg. 275). 
DosWaitThread causes the current thread to suspend until another 
thread terminates (pg. 276). 





@ DosCreateThread Thread Management 





Begins an asynchronous thread of execution in the current process. 


SYNTAX 


APIRET DosCreateThread(PTID pThreadlID, PFNTHREAD pThread- 
Address, ULONG ulThreadArgument, 
ULONG uwlThreadF lags, ULONG 
ulStackSize) 


PARAMETERS 


pThreadID - output 
The address of a TID to receive the thread ID of the created thread. 
pThreadAddress - input 
The address of the function to be executed as a thread. The function 
specified must use system linkage and can only accept one argument— 
ull hreadArgument. 
ulThreadArgument - input 

_ The argument to pass to the newly created thread. Since you can only 
pass one 4byte value as an argument, this value is usually a pointer to 
a structure containing all the values you wish to pass to the thread. If 
no argument is desired, a OL may be specified for this parameter, and 
the thread may be declared as taking a VOID parameter. 
ulThreadFlags - input 
You may bitwise OR the following flags to control the start of the 
thread and the method to be used for the stack allocation: 
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Starting States Description 
CREATE_READY Q The thread will begin execution immediately. 


CREATE_SUSPENDED 1. The thread will be created in a suspended 
state and will only begin execution when a 
DosResumeThread is issued against it. 


Stack Options Description 


STACK _SPARSE Q The stack will use the guard page method for 
stack management (using guard pages), and 
it will have only 4k initially committed, and 
will commit additional memory as needed up 
to the maximum specified in the ulThreadSize 
parameter. 


STACK_COMMITED 2 All stack pages will be committed 
immediately. 


ulStackSize - input 

The size of the stack in bytes. The size will be rounded to the nearest 
4k page boundary. If the size of the stack specified is less than 8k, it will 
be rounded up to 8k (2 pages). The system will automatically deallo- 
cate the stack when the thread terminates. For Presentation Manager 
threads and threads running under the Workplace Shell process, the 
stack should be fairly large—48k is a good starting point. However, 
since stacks can be allocated sparse, there is no harm in declaring 
much larger stack sizes. 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSPROCESS 
Ordinal: 311 DLL: DOSCALLS 

SEE ALSO 


_beginthread, DosEnterCritSec -258, DosExitCritSec -263, 
DosExit -277, DosKillThread -273, DosResumeThread -274, 
DosSuspendThread -275, DosWaitChild -269 


NOTES 


The new thread receives the same priority as the calling thread. 
The thread shares access with all process-level resources: file han- 
dles, pipes, queues, system semaphores, and linear address space. 
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However, each thread receives its own stack and register context. Some 
compiler libraries allow you to set up per-thread storage or storage that 
is allocated and persistent to each thread even though it may have the 
same beginning execution point as another currently executing 
thread. 

Each thread has its own Thread Information Block (TIB) that 
contains per-thread information (such as TID, priority, and so on) that 
is maintained in the user address space. See DosGetInfoBlocks for 
more information. 

Each thread begins execution at the address passed in as 
pThreadAddress via a near call, and ends when a return statement or 
a DosExit is encountered. 

Threads created with the STACK_SPARSE option use the guard 
page method of dynamic stack growth, otherwise the entire stack is 
precommited. If the system runs out of guard pages, then a guard page 
allocation exception will be generated. See DosSetExceptionHandler 
(pg. 38) call for information on how to handle this exception. 


RESTRICTIONS/WARNINGS 


@ If you are using C or C++ library functions, you should use the _be- 
ginthread() function that comes with the compiler. Failure to do so 
can cause unpredictable results when using the C or C++ library 
functions within that thread. 





DosKillThread Thread Management 


Kills the specified thread of the calling process. 


SYNTAX 
APIRET DosKillThread (TID idThread) 


PARAMETERS 
idThread - input 
The ID of the thread to be terminated. 


RETURNS 


0 NO_ERROR 309 ERROR_INVALID_THREADID 
170 ERROR_BUSY 
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OTHER INFO 

Include file: bsedos.h Define: INCL. _DOSPROCESS 
Ordinal: 111 DLL: DOSCALLS 

SEE ALSO 


DosCreateThread -271, DosExit - 277, DosKillProcess -267, 
DosResumeThread - 274, DosSuspendThread -275, 
DosWaitThread -276 


NOTES 


None. 


RESTRICTIONS/WARNINGS 


@® DoskillThread only works on threads running in the current 
process. 

@ You cannot kill the calling thread with this function. You must use 
DosExit (pg. 277) to terminate the current thread. 

@ You cannot kill a thread that is currently blocked on a semaphore. 

@ Ifyou kill thread 1 (the main thread), the entire process ends. 

@ You cannot kill 16-bit threads or threads started by 16-bit routines. 
An attempt to do so will cause ERROR_BUSY to be returned. 

@ This call should only be used as a last resort. 





DosResumeT hread Thread Management 





Restarts threads suspended via DosSuspendThread. 


SYNTAX 
APIRET DosResumeThread (TID zdThread) 


PARAMETERS 
idThread - input 
The ID of the thread to resume normal execution. 


RETURNS 


0 NO_ERROR 90 ERROR _NOT_FROZEN 
309 ERROR_INVALID_THREADID 
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OTHER INFO 

Include file: bsedos.h Define: INCL. DOSPROCESS 
Ordinal: 237 DLL: DOSCALLS 

SEE ALSO 


DosCreateThread -271, DosSuspendThread -275 


NOTES 


This function restarts threads suspended with DosSuspendThread. 
ERROR NOT_FROZEN will be returned if the call is issued 
against a thread that is not suspended. 





DosSuspend Thread Thread Management 


Suspends execution of the specified thread of the current process. 


SYNTAX 
APIRET DosSuspendThread (TID zdThread) 


PARAMETERS 
tdThread - input 
The ID of the thread to be suspended. 


RETURNS 

0 NO_ERROR 309 ERROR _ INVALID THREADID 
OTHER INFO 

Include file: bsedos.h Define: INCL _DOSPROCESS 
Ordinal: 230 DLL: DOSCALLS 

SEE ALSO 


DosEnterCritSec - 258, DosExitCritSec -263, DosResumeThread -274 


NOTES 

The thread may not be suspended if it is waiting on a system call that 
has locked system resources. Once the resources are freed, the call will 
take effect. 
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This call only suspends one thread. You can suspend all threads 
other than the current thread by using DosEnterCritSec (pg. 258). 





DosWait Thread Thread Management 





Waits for the specified thread of the calling process to end. 


SYNTAX 
APIRET DosWaitThread(PTID pThreadID, ULONG ulWaitOption) 


PARAMETERS 


pthreadID - input/output 

On input, the address of the TID that contains the thread ID to wait 
for. If zero is specified for the thread ID, the current thread will wait 
until the next thread in the process terminates. 

ulWaitOption - Input 

Specify one of the following wait options: 


Constant Description 

DCWW_WAIT Q Wait until the specified thread ends. If the 
thread has already ended, the call will return 
immediately. 

DCWW_NOWAIT 1 Don’t wait—return immediately. This option 
is useful to detect whether a thread has 
terminated. 

RETURNS 

0 NO_ERROR 294 ERROR THREAD NOT_ 
TERMINATED 

309 ERROR_INVALID_ THREADID 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSPROCESS 

Ordinal: 349 DLL: DOSCALLS 

SEE ALSO 


DosCreateThread -271, DosWaitChild - 269 
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NOTES 


This call is useful for waiting for a thread to terminate that is running 
code in a DLL that you want to unload, but you don’t want to pull the 
DLL out from under the running thread. This particular situation is 
common in Workplace Shell DLLs. 

If the DOWW_NOWAIT option was specified and the given thread 
has not terminated, the value for the thread ID is preserved. 

The ERROR INVALID THREADID will be returned if either 
the specified thread is the current thread or the main thread (thread 
ID of 1). 


Process/Thread Functions 





DosExit causes one or all threads of the current process to terminate 
(pe. 277). 

DosGetInfoBlocks returns a structure containing per-thread and per- 
process information (pg. 278). 

DosSetPriority sets the priority of a process or a thread running in the 
current process (pg. 280). 





@ DosExit Process Management 


Terminates the calling thread or all threads of a process. 


SYNTAX 
VOID DosExit(ULONG wlActionCode, ULONG wulReturnCode) 


PARAMETERS 

ulActionCode - input 

Specify whether the calling thread or all threads of the process should 
be terminated as follows: 


Constant Description 
EXIT_THREAD Q Exit the calling thread only. 
EXIT_PROCESS 1 Exit all threads of the calling process. 
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ulReturnCode - input 
The exit code for the process. ‘This value is passed to any thread that is- 
sues a DosWaitChild for this process; it is also used when the process is 


terminating to provide a return code to the command processor 
(CMD.EXE). 


RETURNS 
THIS FUNCTION NEVER RETURNS 


OTHER INFO 


Include file: bsedos.h Define: INCL. _DOSPROCESS 
Ordinal: 234 DLL: DOSCALLS 


SEE ALSO 


_endthread, _ exit, exit, DosCreateThread -271, DosExecPgm -259, 


DosExitList -264, DosKillProcess -267, DosKillThread -273 


NOTES 


If the thread executing is the last thread in the process, then the 
process ends and the return code specified in ulReturnCode is returned 
to the command processor. 

When the process is ending, any functions specified in an exit list 
(see DosExitList pg. 264) will be executed. After the exit list is finished 
processing, all resources owned by the process will be freed and the 
process will terminate. 


RESTRICTIONS/WARNINGS 


@ Do not end the main thread (thread 1) using DosExit unless you are 
ending the entire process using the EXIT_PROCESS option, other- 
wise unpredictable results may occur. 

@ If the thread you wish to end was created using the C library 
function _beginthread( ), you should use _endthread( ) to exit, not 
DosExit. 





DosGetInfoBlocks Process/Thread Management 


Returns the Thread Information Block (TIB) and Process Information 
Block (PIB). 
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SYNTAX 
APIRET DosGetInfoBlocks(PTIB *ppiib, PPIB *pppzb) 


PARAMETERS 

*pptib - output 

A pointer to a TIB pointer that will receive the address to the Thread 
Information Block for the calling thread. 

*pppib - output 

A pointer to a PIB pointer that will receive the address to the Process 
Information Block for the calling process. 


RETURNS 
0 NO_ERROR 


OTHER INFO 


Include file: bsedos.h Define: INCL. _DOSPROCESS 
Ordinal: 312 DLL: DOSCALLS 


SEE ALSO 
_getpid, _get I[Bvalue 


NOTES 


The Process Information Block provides read/write access to per- 
process information stored in doubleword fields such as the PID, par- 
ent PID, module handle, command line address, environment block 
address, process status, and the type of process. See the PIB structure 
on page 283 for more information. 

The Thread Information Block provides read/write access to per- 
thread information stored in doubleword fields such as the exception 
handler chain, address to the base of the thread’s stack, address of the 
end of the stack, address of the OS-specific Thread Information Block, 
TIB version number, and the thread’s ordinal number. See the TIB 
structure on page 284 for more information. 

The OS-specific Thread Information Block contains the following 
information: thread ID, thread priority, version number of this block, 
and the must-complete count. See the TIB2 structure on page 285 for 
more information. 
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@® DosSetPriority Process/Thread Management 


Changes the default priority of a thread, process, or process tree. 


SYNTAX 


APIRET DosSetPriority(ULONG wlScope, ULONG ulPniorityClass, 
LONG /PnorntyDelia, ULONG ulD) 


PARAMETERS 
ulScope - input 
Specify one of the following values for the scope of the change: 


Constant Description 


PRTYS_PROCESS Q Change the priority of all threads of the given 
process. This can be any process. 


PRTYS_PROCESSTREE 1 Change the priority of all threads of the 
specified process and its children. The 
process must be either the calling process or 
a child process created by the calling process. 
Detached processes are not affected. The 
target process may have terminated. 


PRTYS_ THREAD 2 Change the priority of the specified thread of 
the calling process. 


ulPriority Class - input 
Specify one of the following priority classes: 


Constant Description 
PRTYC_NOCHANGE Q Do not change the priority class. 
PRTYC_IDLETIME 1 Set to Idle time class. Idle time threads 


are the lowest priority class and only 
receive execution time when there are 
no other threads of a higher priority 
class ready to run. This class never 
receives priority adjustments by the 
system. 


PRTYC_REGULAR 2 Set to Regular class. This is the default 
priority class, and most threads run in 
this class. ‘This class is dispatched only 
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when there are no Time Critical or 
Foreground Server threads ready to 
run. This class will receive priority 
adjustments. See the Notes section. 


PRTYC_TIMECRITICAL 3 Set to Time Critical class. This class has 
the highest priority in the system. 
These threads are serviced before all 
other threads of all other classes. ‘This 
class never receives priority 
adjustments. 


PRTYC_FOREGROUNDSERVER 4 Set to Foreground Server class. This 
class of threads is serviced before 
any Regular class or Idle Time class 
threads, but only after there are no 
Time Critical threads ready to run. 
This class never receives priority 
adjustments. 


lPriorityDelta - input 

Specify the priority level as follows: If the priority class is being 
changed, then /PriontyDelta is relative to zero. Priority levels range from 
0 to 31 (PRTYD_MAXIMUM), with 31 being the highest priority. If 
PRTYC_NOCHANGE was specified for ulPnontyClass, then lPriority- 
Delta is relative to the current priority level. ‘This value can range from 
-31 (PRTYD_MINIMUM) to +31 (PRTYD_MAXIMUM). 

ullD - input 

The process ID (if ulScope = PRTYS_PROCESS or PRTYS_PROCESS- 
TREE) or the thread ID (if ulScope = PRTYS_THREAD) to receive the 
priority change. If zero is used, then the current process or thread is as- 
sumed. 


RETURNS 
0 NO_ERROR 307 ERROR_INVALID_ACCESS 
303 ERROR_INVALID_ 308 ERROR_INVALID SCOPE 
PROCID 
304 ERROR_INVALID _ 309 ERROR_INVALID_THREADID 
PDELTA 


305 ERROR_ NOT_DESCENDANT 


OTHER INFO 
Include file: bsedos.h Define: INCL. DOSPROCESS 
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Ordinal: 236 DLL: DOSCALLS 


SEE ALSO 
DosEnterCritSec -258, DosGetInfoBlocks -278 


NOTES 


Threads of the same priority class and delta are serviced in round- 
robin fashion. A thread with a higher delta than another thread of the 
same class will always get its timeslice first. If a thread of a higher pri- 
ority class becomes ready to run while a thread of a lower priority class 
is running, the lower priority thread will lose the remainder of its 
timeslice to the higher priority class thread. 

Use DosGetInfoBlocks (pg. 278) to determine the priority of the 
current thread. 


RESTRICTIONS/WARNINGS 


@ This call only affects the base priority. Base priority refers to the pri- 
ority the thread is set to before the system adjusts it. The system will 
still boost the priority of regular class threads for any of the follow- 
ing reasons: 

1) The MAXWAIT value specified in CONFIG.SYS has been ex- 
ceeded for a thread that is ready to run. Threads in this state are 
known as starved threads, and will receive a boost in class to 
Foreground Server. 

2) For threads where the process is currently running in the fore- 
ground. This is to provide better response time to the applica- 
tion that the user is currently working with. If PRIORITY = AB- 
SOLUTE in CONFIG.SYS, then this boost will not occur. 

3) The process is running in the foreground and the thread has 
been doing disk I/O. This only occurs for a short period after the 
I/O, and only if the PRIORITY_DISK_IO is set to YES in CON- 
FIG.SYS. In this case, the boost will increase the priority level to 
the highest level within the priority class. 

@ The thread receiving the boost will have its timeslice adjusted to the 
minimum timeslice level (specified by the TIMESLICE in CON- 
FIG.SYS). The priority boosts last for the length of the timeslice of 
the boosted thread, and then it is reset to its base value. 

@ Changing the priority of threads running in other processes only af- 
fects the threads still running with the default priority. In other 
words, if the thread running in that other process manually changes 
its priority the request is ignored. 
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® Careless use of DosSetPriority can cause poor performance of other 
processes running on the system. If there is code that needs to be 
completed quickly, it is recommended that DosEnterCritSec be used 
instead. 


Process/Thread Structures 





pib_ulpid (ULONG) 0 
The process ID. 

pib_ulppid (ULONG) 4 
The parent process ID. 

pib_hmted (ULONG) 8 
The module handle of the executable. 

pib_pchcmd (PCHAR) 12 


Pointer to the command line. Programs started normally will have the following format for 
pib_pchcmd: 
“executable name\Qargl1\0arg2\0arg3\0argN\0” 


pib_pchenv (PCHAR) 16 
Pointer to the environment block. Each environment setting is null-delimited, with the final 
setting double null-terminated. New environment settings may be added up to a maximum 
of 64k. The system sparsely allocates memory for the environment 4k at a time. Any changes 
or additions to the environment only affect the process identified by pzb_ulpid. 


pib_flstatus (ULONG) 20 
Program status bits. 
pib_ultype (ULONG) 24 


Process type code. This field maps to PROG_* values found in PMSHL.H. 
Used by: DosGetInfoBlocks -278 





codeTerminate (ULONG) 0 
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For processes that are started asynchronously, this contains the process ID of the child 
process. For synchronous processes, it contains one of the following termination codes: 


Constant Description 
TC_EXIT 0 Normal termination. 
TC_HARDERROR 1 Process terminated due to hard error. 
TC_TRAP 2 Atrap occurred for the 16-bit process. 
TC_KILLPROCESS 3 Unintercepted DosKillProcess. 
TC_EXCEPTION 4 An exception occurred for the 32-bit child process. 


codeResult (ULONG) 4 
The return code specified in the DosExit call of the child process. 


Used by: DosExecPgm -259, DosWaitChild -269 





tib_pexchain (PVOID) 0 
Pointer to the head of the exception handler chain. 

tib_pstack (PVOID) 4 
Pointer to the base of the stack. 

tib_pstacklimit (PVOID) 8 
Pointer to the end of the stack. 

tib_ptib2 (PTIB2) 12 
Pointer to the TIB2 structure. This structure contains OS-specific information. 
tib_version (ULONG) 16 


Version number of this PIB structure. For 2.x versions of the operating system, this value will 
be 20. 


tib_ordinal (ULONG) 20 
A system-wide unique value that represents the thread. This equates to the “slot” number in 
the kernel debugger. 


Used by: DosGetInfoBlocks -278 
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tib2_ultid (ULONG) 0 
The thread id. 
tib2_ulpri (ULONG) 4 


The priority of the thread. The low byte of the low word contains the priority delta, and the 
high byte of the low word contains the priority class. The high word is always zero. See page 
280 for more information on thread priorities. 


tib2 version (ULONG) 8 


Version number of this structure. For 2.x versions of the operating system, this value will be 20. 


tib2_usMCCount (USHORT) 12 


The must-complete count. See DosEnterMustComplete on page 46 for more information. 


tib2_fMCForceFlag (USHORT) 14 


The must-complete force flag. 


Used by: DosGetInfoBlocks -278 





Queues 


286 





ueues are one of the three basic forms of interprocess communi- 

cation supported by OS/2. They are typically less complex to im- 
plement than named pipes because a separate instance of the queue is 
not required for each simultaneously connected client, and queue in- 
formation can only travel one way—from client to server. Unlike pipes, 
however, queues cannot transfer information across a LAN. 

Information is passed through queues in the form of elements. 
Elements are byte values that are written by a client process and read 
by a server process. There can be any number of client processes, but 
only one server process. Only the server can read queue elements, but 
any client and the server may write queue elements. The order that el- 
ements are read from a queue is determined at the time the queue is 
created. The ordering options are FIFO (first-in-first-out), LIFO (last- 
in-first-out—like a stack), or priority-based. For priority-based queues, 
the client that is writing the queue element determines its priority. 
Priority values can range from 0 to 15 with 15 being the highest prior- 
ity. When elements are read from a priority-based queue they will be 
returned highest priority first. 

Since queues are only capable of passing 4-byte values, programs 
typically allocate shared memory (using DosAllocNamedSharedMem) 
that contains the information to be processed, and pass the pointer to 
the memory as the queue element. If the data pointed to by the ele- 
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ment is typically made up of small blocks, it is a good idea for the 
server to suballocate the shared memory object using DosSubSetMem. 

The server has the option of blocking on the DosReadQueue call 
when it’s waiting for data to arrive or to pass an event semaphore han- 
dle to DosReadQueue and then calling DosWaitEventSem. The system 
will post the semaphore when an element has arrived. The server has 
the option of peeking at queue elements (using DosPeekQueue) with- 
out removing them from the queue. DosPeekQueue can peek at the el- 
ements in the order they would be read or in the order that they were 
written to the queue. 

The following sequence is an example of typical queue manage- 
ment: 


1. The server allocates a named shared memory object using DosAlloc- 
SharedMem. The name of the shared memory object is often the 
same as that of the queue, except that the prefix is \SHAREMEM\ in- 
stead of \QUEUES\ Generally, it is a good idea to set up the shared 
memory object as a heap using DosSubSetMem. 

. The server creates the queue with the appropriate ordering option. 

3. The client accesses the shared memory object using DosGetNamed- 
SharedMem. 

4. The client obtains access to the queue using DosOpenQueue. 

5. The client suballocates memory from the named shared memory 
object and fills in the appropriate data. The client then places the 
pointer to the data in the queue using DosWriteQueue. 

6. The server reads the elements from the queue using DosRead- 
Queue. The server may choose to block on DosReadQueue, or have 
DosReadQueue return immediately and then post an event sema- 
phore when there is a queue element to be read. 

7. The server processes the data and then frees the suballocated mem- 
Ory. 

8. Steps 5 through 7 are repeated until it is time to destroy the queue. 

9. The clients issue DosCloseQueue to discontinue access to the 
queue. When the server calls DosCloseQueue the queue is deleted 
from memory. 


NO 


Warnings and Restrictions 


@ OS/2 queues should not be confused with the Presentation 
Manager message queues and printer queues. There is no way for 
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OS/2 queues to communicate with Presentation Manager message 
queues or printer queues. 

@ The system allocates a 64k buffer to manage all queues in the sys- 
tem. The maximum number of simultaneous queues depends on 
the length of the queue names and the number of queues that are 
opened by client processes. See the Notes section of DosCreate- 
Queue for more information on queue limits. 

@ The maximum number of elements that will fit in a queue is 3268. 


Server or Client Process Queue Functions 





DosCloseQueue discontinues access to a queue when called by the 
client process. It frees the queue from the system when called by the 
server process (pg. 288). 

DosQueryQueue returns the number of elements in a queue 


(pg. 289). 


DosWriteQueue writes an element to a queue (pg. 290). 





@® DosCloseQueue Queues 


[Client and Server Processes | 
Discontinues access to a queue or deletes a queue from system memory. 


SYNTAX 
APIRET DosCloseQueue (HQUEUVE hqQueue) 


PARAMETERS 


hqQueue - input 
The handle of the queue to close. 


RETURNS 

0 NO_ERROR 337 ERROR_QUE_INVALID_HANDLE 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSQUEUES 


Ordinal: 11 DLL: QUECALLS 
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SEE ALSO 
DosCreateQueue -291, DosOpenQueue -299, DosQueryQueue -289 


NOTES 


When called by a client process, this call decrements the usage count 
for that process. If the usage count reaches zero, then the process no 
longer has access to the queue. Any elements in the queue are unaf- 
fected. 

When called by the server process, the call purges any elements in 
the queue and frees the queue from system memory even if client 
processes still have access to the queue. If a client process attempts to 
work with the queue after it is closed, it will receive an ERROR_ 
QUE_INVALID_HANDLE return code. 





DosQueryQueue Queues 


[Client and Server Processes] 
Returns the number of elements in the queue. 


SYNTAX 

APIRET DosQueryQueue(HQUEUE hgQueue, PULONG 
pulNumOfElements) 

PARAMETERS 


hqQueue - input 

The handle of the queue to query. 

pulNumOfElements - output 

The address of a ULONG to receive the number of queue elements. 


RETURNS 

QO NO_ERROR 337 ERROR_QUE_INVALID_HANDLE 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSQUEUES 
Ordinal: 12 DLL: QUECALLS 

SEE ALSO 


DosCreateQueue -291, DosOpenQueue -299, DosPeekQueue -293, 
DosPurgeQueue -296, DosReadQueue -296, DosWriteQueue -290 
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NOTES 


This call can be made by any process that has access to the queue. 
If the queue has been closed, or a bogus handle value has been 
specified, then ERROR_QUE_INVALID_HANDLE is returned. 





DosWriteQueue Queues 


[Client and Server Processes | 
Adds an element to a queue. 


SYNTAX 


APIRET DosWriteQueue (HQUEUE hqQueue, ULONG ulRequest, 
ULONG uwlDataLength, PVOID pData, 
ULONG ulPnonty) 


PARAMETERS 

hqQueue - input 

The handle of the queue to add the element to. 

ulRequest - input 

A user-defined field that is typically used to indicate the nature of the 
element that was written to the queue. The system does not use or 
modify this field, but returns it to the server when DosReadQueue or 
DosPeekQueue is used. 

ulDataLength - input 

The length of the data, in bytes, that the element points to. 

pData - input 

Usually this is an address that points to a shared memory area that con- 
tains the data to be processed by the server process. However, any 4 
byte value can be passed for pData (casting may be necessary). 
ulPriority - input 

The priority of the element to be added. This value is only checked for 
priority-based queues. Priorities can range from 0 to 15 with 15 being 
the highest priority. If a value higher than 15 is specified, the system 
will change it to 15 and not return an error. Elements with the highest 
priority are read first, with elements of the same priority being read 
first-in first-out. 


RETURNS 


0 NO_ERROR 334 ERROR_QUEUE_NO_MEMORY 
337 ERROR_QUE_INVALID_HANDLE 
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OTHER INFO 

Include file: bsedos.h Define: INCL_DOSQUEUES 
Ordinal: 14 DLL: QUECALLS 

SEE ALSO 


DosCreateQueue -291, DosOpenQueue -299, DosPeekQueue -293, 
DosPurgeQueue -296, DosQueryQueue -289, DosReadQueue -296 


NOTES 


All processes except for the server process must obtain access (see 
DosOpenQueue, pg. 299) to the queue before calling this function. 

If the queue is closed, or a bogus handle is specified, then ER- 
ROR_QUE_INVALID_HANDLE is returned. 

Usually, the OS/2 suballocation functions are used to allocate 
memory for queue elements. When using these functions, the process 
writing to the queue allocates the suballocated block, and the server 
frees the block when it has finished processing it. 


Server Process Queue Functions 





DosCreateQueue creates a FIFO, LIFO, or priority-based OS/2 queue 
(pg. 291). 

DosPeekQueue allows queue elements to be examined without re- 
moving them (pg. 293). 

DosPurgeQueue deletes all elements in a queue (pg. 296). 
DosReadQueue reads and removes a queue element from a queue 





(pg. 296). 
@ DosCreateQueue Queues 


[Server Processes] 
Creates an OS/2 queue. 


SYNTAX 


APIRET DosCreateQueue(PHQUEUE phqQueue, ULONG 
ulQueuef lags, PSZ pszQueueName) 
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PARAMETERS 

phqQueue - output 

A pointer to an HQUEUE that will receive the handle of the newly cre- 
ated queue. 

ulQueueFlags - input 

Specify the following options (the default is in italics): 


Ordering Options = Description 
QUE_FIFO Q Create a FIFO queue. 
QUE_LIFO 1 Create a LIFO queue. 
QUE_PRIORITY 2 Create a priority-based queue. 


Priorities range from 0 to 15. 


Address Conversion Options = Description 


QUE_NOCONVERT_ADDRESS Q The addresses referred to by queue 
elements that are written by 16-bit 
processes will not be converted to 32- 
bit. 


QUE_CONVERT_ADDRESS 4 The addresses referred to by queue 
elements that are written by 16-bit 
processes will be converted to 32-bit 
addresses. 


pszQueueName - input 

A pointer to a buffer that contains the null-terminated name of the 
queue to create. The queue name must have the prefix \QQUEUK\, and 
must follow file system naming conventions. The queue name is used 
by client processes to open the queue. 


RETURNS 
0 NO_ERROR 334 ERROR _QUE_NO_MEMORY 
87 ERROR_INVALID 335 ERROR_QUE_INVALID_ 
PARAMETER NAME 
332 ERROR_QUE_DUPLICATE 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSQUEUES 


Ordinal: 16 DLL: QUECALLS 
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SEE ALSO 


DosCloseQueue -288, DosOpenQueue -299, DosQueryQueue -289, 
DosReadQueue -296, DosWriteQueue -290 


NOTES 


The process that issues this call is referred to as the server process. The 
server process need not open the queue to use the queue. 

OS/2 allocates a 64k buffer to manage all of the queues in the sys- 
tem. The number of queues available to applications is dependent on 
several factors: 


@ The number of queues used by the system and other applications. 
@ The length of the names of the queues. If short queue names are 
used, then far more queues can be created and opened by client 
processes. The longer the name, the fewer number of simultaneous 
queues that are supported by the system. 

The number of queues that will be opened simultaneously by client 
processes. Additional memory is used in the system’s internal queue 
buffer when a queue is opened by a child process (the child’s PID 
must be stored). Therefore, it is possible to successfully create 
queues that cannot be opened because the process of opening the 
queue requires memory. 


Based on these factors, the number of queues available for an applica- 
tion will typically range from 1000 to 2000. When the system cannot 
create any more queues, ERROR_QUE_ NO_MEMORY is returned. 

If the queue to be created already exists, then ERROR_QUE_DU- 
PLICATE is returned. 

If the queue name specified does not follow file-naming conven- 
tions or lacks the \QUEUE\ prefix, then ERROR_QUE_INVALID_ 
NAME is returned. 

If any bits are set for ulQueueFlags other than the ones docu- 
mented previously, then ERROR_INVALID_PARAMETER is returned. 





DosPeekQueue Queues 


[Server Processes] 
Examines an element in a queue without removing it. 
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SYNTAX 


DosPeekQueue (HQUEUE hgQueue, PREQUESTDATA pRequestData, 
PULONG pulDataLength, PPVOID ppElementValue, 
PULONG pulElemeniCode, BOOL32 [32NoWait, 
PBYTE pbElementPnonty, HEV hevSemaphore) 


PARAMETERS 


hqQueue - input 

The handle of the queue containing the element to examine. 
pRequestData - output 

The address of a REQUESTDATA structure that will receive the PID of 
the queue element that is being examined, and the user data value that 
was specified when the queue element was written. 

pulDataLength - output 

The address of a ULONG that will receive the length of the data the ele- 
ment refers to. This is the same value as was specified for ulDataLength 
when DosWriteQueue was called. 

ppElementValue - output 

The address of a PVOID that will receive the value of the element. If 
QUE_CONVERT_ADDRESS was specified when the queue was cre- 
ated and the element was written by a 16-bit process, then this value 
represents the converted address. 

pulElementCode - input/output 

On input, the address of a ULONG that contains either a zero, which 
indicates that the next element in the queue that would be removed by 
a DosReadQueue (according to the ordering option that was speci- 
fied) is to be examined; or a nonzero value, which indicates that the 
next element in the queue after this one is to be examined. When this 
option is used, the value on output is that of the queue element that 
was examined. This option can be used to step through each element 
in the queue with subsequent calls to DosPeekQueue. 

f32NoWait - input 

Specify the desired wait option: 


Constant = Description 


DCWW_WAIT 0 The calling thread will block until there is a 
queue element that can be examined. 


DCWW_NOWAIT 1 The calling thread will return immediately even if 
there is no element to examine. If there is no ele- 
ment to examine, then ERROR_QUE_EMPTY is 
returned. When this option is used, a semaphore 
handle must be specified for hevSemaphore. 
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pbElementPriority - output 

The address of a PBYTE that will receive the priority value of the ele- 
ment. This information is only returned for priority-based queues. 
hevSemaphore - input 

The handle of an event semaphore to post when there is data available 
to be examined in the queue and the DOWW_NOWAIT option was 
specified. The specified semaphore handle is saved by the system and 
must be used for all subsequent calls to DosPeekQueue and DosRead- 
Queue that have this queue as their target. 


RETURNS 
0 NO_ERROR 337 ERROR_QUE_INVALID_HANDLE 

87 ERROR INVALID _ 340 ERROR_QUE_PREV_AT_ 
PARAMETER END 

330 ERROR PROC __ 342 ERROR_QUE_ 
NOT_OWNED EMPTY 

333 ERROR_QUE_ 433 ERROR_QUE_INVALID_WAIT 
ELEMENT NOT_EXIST 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSQUEUES 

Ordinal: 13 DLL: DOSCALLS 

SEE ALSO 


DosCreateEventSem -307, DosCreateQueue -291, 
DosOpenQueue -299, DosPurgeQueue -296, DosQueryEventSem -310, 
DosReadQueue -296, DosWriteQueue -290 


NOTES 


When the DOWW_NOWAIT option is used, the system will automati- 
cally open and post the event semaphore specified in heuSemaphore 
whenever an element is written to the queue. DosWaitEventSem may 
be used to block or poll the semaphore. After the semaphore is posted, 
the server must call DosPeekQueue for each increment of the post 
count to examine the new elements. It is the responsibility of the caller 
to reset the event semaphore when needed. 


RESTRICTIONS/WARNINGS 


@ This call can only be used by the threads of the server process. 
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@ The first event semaphore passed to DosPeekQueue or DosRead- 
Queue is stored by the system and must be used for all subsequent 
peek or read requests made against the same queue. If a different 
handle is specified, then ERROR_INVALID PARAMETER is re- 
turned. 

@ When the NOWAIT option is used, a semaphore handle must be 
specified for heuSemaphore. 





DosPurgeQueue Queues 


[Server Processes | 
Purges all queue elements from a queue. 


SYNTAX 
APIRET DosPurgeQueue (HQUEUE hgQueue) 


PARAMETERS 


hqQueue - input 
The handle of the queue to be purged. 


RETURNS 


0 NO_ERROR 337 ERROR_QUE_PROC_ 
NOT_OWNED 
330 ERROR_QUE_INVALID_HANDLE 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSQUEUES 
Ordinal: 10 DLL: QUECALLS 

SEE ALSO 


DosCreateQueue -291, DosOpenQueue -299, DosPeekQueue -293, 
DosReadQueue -296, DosWriteQueue -290 


RESTRICTIONS/WARNINGS 
@ This call can only be invoked by the threads of the server process. 
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@ DosReadQueue Queues 


[Server Processes] 
Reads and removes an element from a queue. 


SYNTAX 


APIRET DosReadQueue (HQUEUE hqQueue, PREQUESTDATA 
pRequestData, PULONG pulDataLength, 
PPVOID ppDataAddress, ULONG 
ulElementCode, BOOL32 f32NoWait, PBYTE 
pbElementPrionty, HEV hevSemaphore) 


PARAMETERS 

hqQueue - input 

The handle of the queue to read. 

pRequestData - output 

The address of a REQUESTDATA structure. The REQUESTDATA 
structure contains the process ID of the process that wrote the element 
to the queue, and the value of that specified for ulRequest on the 
DosWriteQueue call. 

pulDataLength - output 

The address of a ULONG to receive the number of bytes the queue 
element refers to. 

ppDataAddress - output 

The address of a PVOID that will receive the element. This value will 
be different than the value specified when the element was added, if 
the queue was created with the QUE_CONVERT_ADDRESS option, 
and the queue element was added by a 16-bit process; in this case, the 
element will be converted to 32-bit. 

ulElementCode - input 

If zero, the first element in the queue will be removed with respect to 
the queue’s ordering method (either FIFO, LIFO, or priority). If this 
field is not zero, then it must refer to the ID of an element that was re- 
turned from the pulElementCode parameter of DosPeekQueue. 
f22NoWait - input 

Specify the desired wait option: 


Constant = Description 


DCWW_WAIT 0 The calling thread will block until there is a 
queue element that can be read. 


298 


OS/2® Warp Control Program API 


DCWW_NOWAIT 1 The calling thread will return immediately 
even if there is no element to read. If there is 
no element to read, then ERROR_QUE_- 
EMPTY is returned. When this option is used, 
a semaphore handle must be specified for 
hevSemaphore. 


pbElementPriority - output 

The address of a PBYTE that will receive the priority value of the ele- 
ment. This information is only returned for priority-based queues. 
hevSemaphore - input 

The handle of an event semaphore to post when there is data available 
to be read by the queue and the DOWW_NOWAIT option was speci- 
fied. The specified semaphore handle is saved by the system and must 
be used for all subsequent calls to DosPeekKQueue and DosReadQueue 
that have the same queue as their targets. 


RETURNS 


0 NO_ERROR 337 ERROR_QUE_INVALID_HANDLE 
87 ERROR_INVALID_ 342 ERROR_QUE_EMPTY 
PARAMETER 
330 ERROR_QUE_ 433, ERROR_QUE_INVALID_WAIT 
PROC_NOT_OWNED 
333 ERROR_QUE_ELEMENT_NOT_EXIST 


OTHER INFO 

Include file: bsedos.h Define: INCL_DOSQUEUES 
Ordinal: 9 DLL: QUECALLS 

SEE ALSO 


DosCreateEventSem -307, DosCreateQueue -291, 

DosOpenQueu -299, DosPeekQueue -293, DosPurgeQueue -296, 
DosQueryEventSem -310, DosQueryQueue -289, DosReadQueue -296, 
DosWriteQueue -290 


NOTES 


When the DOWW_NOWAIT option is used, the system will automati- 
cally open and post the event semaphore specified in hevSemaphore 
whenever an element is written to the queue. DosWaitEventSem may 
be used to block or poll the semaphore. After the semaphore is posted 
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the server should call DosReadQueue for each increment of the post 
count to examine the new elements. It is the responsibility of the caller 
to reset the event semaphore when needed. 


RESTRICTIONS/WARNINGS 


@ This call can only be used by the threads of the server process. 

@ The first event semaphore passed to DosPeekQueue or DosRead- 
Queue is stored by the system, and must be used for all subsequent 
peek or read requests made against the same queue. If a different 
handle is specified, then ERROR_INVALID_PARAMETER is re- 
turned. 

@ When the NOWAIT option is used, a semaphore handle must be 
specified for hevSemaphore. 


Client Process Queue Functions 





DosOpenQueue obtains access to a queue for a client process (pg. 
But )'s 
DosQueryQueue returns the number of elements in a queue (pg. 


289). 





@ DosOpenQueue Queues 


[Client Processes | 
Obtains access to a queue for a client process. 


SYNTAX 

APIRET DosOpenQueue(PPID ppidOwner, PHQUEUE phgQueue, PSZ 
pszQueueName) 

PARAMETERS 


ppidOwner - output 
The address of a PID that will receive the process ID of the server 
process. 


phqQueue - output 
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The address of a QUEUE that will receive the handle of the opened 
queue. 

pszQueueName - input 

A pointer to a buffer containing the null-terminated name of the 
queue to open. This name must match the name specified when the 
queue was created (see DosCreateQueue -291). 


RETURNS 

0 NO_ERROR 341 ERROR_QUE_PROC_NO_ACCESS 
334 ERROR_QUE_NO_ 343 ERROR_QUE_ NAME NOT_EXIST 

MEMORY 

OTHER INFO 
Include file: bsedos.h Define: INCL_DOSQUEUVES 
Ordinal: 15 DLL: QUECALLS 
SEE ALSO 


DosCloseQueue -288, DosCreateQueue -291, DosQueryQueue -289, 
DosWriteQueue -290 


NOTES 


Obtains access to a queue for a client process and increments the us- 
age count for the process by 1. 

Queues created by 16-bit processes cannot be opened by 32-bit 
DosOpenQueue interfaces, and an attempt to do so will return 
ERROR_QUE_PROC_NO_ACCESS. 

If the queue name specified does not exist, then ERROR_QUE_ 
NAME NOT_ EXIST is returned. 

If there is not enough memory in the internal buffer for queues, 
then ERROR_QUE_NO_MEMORY is returned. It is possible to create 
queues and then not be able to open them due to a lack of memory in 
the system’s internal queue buffer. See the Notes section of DosCreate- 
Queue for more information. 
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Queue Structures 





pid (PID) 0 
The process ID of the process that added the element to the queue. 
ulData (ULONG) 4 


The value of ulRequest that was specified on DosWriteQueue. This is a user-defined field that 
is not modified or checked by the system in any way. 


Used by: DosPeekQueue -293, DosReadQueue -296 


@15. 
Semapnores 
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i multitasking environments there are many occasions when a pro- 
gram needs to wait for a certain event to occur before execution can 
continue, or when a program needs to ensure that sections of code can 
only be entered by one thread at a time. In OS/2, semaphores are used 
to provide control in these situations. Semaphores can be thought of 
as traffic lights. They allow only one stream of traffic to flow at a time, 
or only allow the crossing guards at a train crossing to come down 
when there is a train coming. All OS/2 semaphores can be either pri- 
vate to a given process or shared among many processes. OS/2 pro- 
vides two basic types of semaphores, and one combined semaphore. 


Event Semaphores 


Event semaphores are used when a program must wait for a certain 
event to occur before continuing execution of a thread. When the 
event occurs, the semaphore is “posted” and any threads blocked on 
the semaphore continue execution. Event semaphores have post 
counts which indicate the number of times the semaphore was posted. 
Semaphores with a post count of zero are said to be “set.” The sema- 
phore’s post count can be reset at any time by any process that has ac- 
cess to the semaphore. 


Semaphores 303 


Event semaphores are created by calling DosCreateEventSem. All 
threads of the process that created the shared event semaphore have 
immediate access to the semaphore. Other processes can obtain access 
to a shared event semaphore by calling DosOpenEventSem. Any 
thread that issues a DosWaitEventSem on a “set” semaphore will be 
blocked until the semaphore is “posted.” A semaphore is considered 
set if its post count is zero. An event semaphore is posted by calling 
DosPostEventSem. The post count of the given semaphore goes up by 
one, and all threads that are blocked on that semaphore become un- 
blocked. An event semaphore only needs to be posted once before 
blocked threads will be released. The post count is used by the blocked 
thread to determine the number of times the given event occurred. 
The post count for an event semaphore can go up to 65535 before an 
error is returned. Note: An error will be returned for any post that oc- 
curs after the first post, but the post count will be incremented anyway. 
DosResetEventSem resets the post count back to zero. 

Event semaphores are edge-triggered; that is, a thread waiting on 
an event semaphore that is posted and reset before the waiting thread 
gets a chance to run will still act as if the semaphore is posted for the 
remainder of the thread’s waiting period. To put it simply, the blocked 
thread will begin execution as if the semaphore is still posted, but the 
next time it waits for the semaphore, it will block. 

When blocking on an event semaphore in a PM thread, WinWait- 
EventSem should be used instead of DosWaitEventSem. This will allow 
the message queue for the PM thread to continue processing while 
blocked on an event semaphore. 


Mutual Exclusion Semaphores 


Mutual exclusion (or mutex) semaphores ensure that no two threads 
will enter the same piece of code at the same time. For example, a pro- 
gram may have created a memory object that could be written to or 
read from by multiple threads. Obviously, you wouldn’t want one 
thread to be changing data in the memory object while another is try- 
ing to read it. In this case, a mutex semaphore can be used to ensure 
that only one thread will have access to the memory object at a time. 
Mutex semaphores are created using DosCreateMutexSem. All 
threads of the creating process have immediate access to the sema- 
phore. Other processes can obtain access to shared mutex semaphores 
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by calling DosOpenMutexSem. DosRequestMutexSem is used to mark 
the beginning of the code to be serialized, and DosReleaseMutexSem 
marks the end of it. 

The system allows access to the protected section of code based on 
the priority and order of the request of the waiting thread. If two 
threads that are blocking on the semaphore have the same priority, 
they will be given ownership to it FIFO (first-in-first-out); otherwise, 
the thread with the higher priority will be given ownership first. 

Mutex semaphores are level-triggered, meaning that a thread that 
is blocked on a semaphore will never know that other threads may 
have taken ownership and released ownership of the semaphore while 
the blocked thread was waiting. Threads that are blocked on a mutex 
semaphore are still periodically dispatched by the scheduler. A thread 
that is dispatched by the scheduler and is blocked on the mutex sema- 
phore will check the state of the semaphore. If the semaphore is un- 
owned it will take ownership of it, otherwise it will be placed in the 
ready state and placed back onto the beginning of the dispatch queue. 

It is important for processes that are using shared mutex sema- 
phores to have exit list processing to release any shared mutex sema- 
phores they have ownership of before terminating. 


Muxwait Semaphores 


Muxwait semaphores are actually collections of either event sema- 
phores or mutex semaphores. When creating a muxwait semaphore, a 
list of semaphores is supplied that indicates which semaphores are to 
be waited on. The call also allows you to see whether waits will occur 
until one or all semaphores post (for event semaphores) or release 
ownership (for mutex semaphores). You cannot mix event and mutex 
semaphores when creating a muxwait semaphore, however, you can 
mix private and shared semaphores. Muxwait semaphores are level- 
triggered, explained in the previous discussion on Mutex Semaphores. 

Muxwait semaphores are created by passing a list of semaphores to 
DosCreateMuxWaitSem. All threads of the creating process have im- 
mediate access to the semaphore. Other processes can obtain access to 
a shared muxwait semaphore by calling DosOpenMuxWaitSem. If a 
shared muxwait semaphore is being created, all processes that will be 
using the semaphore must have access to every semaphore in the 
muxwait list, otherwise an error is returned. Threads can block on a 
muxwait semaphore by calling DosWaitMuxWaitSem. Semaphores can 
be added to a muxwait semaphore’s list by calling DosAddMux- 
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WaitSem, and removed by calling DosDeleteMuxWaitSem. If a sema- 
phore is being added to a shared muxwait semaphore, every process 
that has access to the muxwait semaphore must have access to the sem- 
aphore being added, otherwise, any blocked threads in a process that 
does not have access to the newly added semaphore will unblock and 
return an error. 

When blocking on muxwait semaphores in PM threads, Win- 
WaitMuxWaitSem should be used instead of DosWaitMuxWaitSem to 
ensure that the message queue for the thread can be serviced while 
blocked on a muxwait semaphore. 


Warnings and Restrictions 


@ The maximum number of private semaphores is 65536. 

@ The maximum number of shared semaphores is 65536. 

@ The maximum post count for event semaphores is 65535. 

@ The maximum number of open requests for a semaphore across all 
processes is 65535. 

@ RAM and FSRAM semaphores are not available in the 32-bit APIs 
due to portability. 


Event Semaphore Functions 





DosCloseEventSem decrements the usage count of an event sema- 
phore. If the usage count equals zero, then the semaphore is deleted 
from the system (pg. 306). 

DosCreateEventSem creates a private or shared event semaphore 
(pg. 307). 

DosOpenEventSem obtains access for the current process to a shared 
event semaphore (pg. 308). 

DosPostEventSem posts an event semaphore (pg. 309). 
DosQueryEventSem returns the post count of an event semaphore 
(pg. 310). 

DosResetEventSem resets the post count of an event semaphore to 
zero (pg. 311). 

DosWaitEventSem blocks the calling thread until the specified event 
semaphore is posted (pg. 312). 
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@ DosCloseEventSem Semaphores 


Decrements the usage count for the specified event semaphore and/ 
or frees the semaphore. 


SYNTAX 
APIRET DosCloseEventSem (HEV hevSemaphore) 


PARAMETERS 

hevSemaphore - input 

The handle of the event semaphore whose usage count will be decre- 
mented. 


RETURNS 

0 NO_ERROR 301 ERROR _ SEM BUSY 

6 ERROR INVALID HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 
Ordinal: 326 DLL: DOSCALLS 

SEE ALSO 


DosCreateEventSem -307, DosOpenEventSem -308, 
DosPostEventSem -309, DosQueryEventSem -310, 
DosResetEventSem -311, DosWaitEventSem -31? 


NOTES 


For unnamed, nonshared semaphores, this call frees the semaphore 
resource from the system. 

For unnamed shared semaphores, this call discontinues access to 
the semaphore for the calling process, and if there are no other 
processes accessing the semaphore, the semaphore is freed from the 
system. 

For named semaphores, this call will decrement the usage count 
of the target semaphore by one. If the usage count reaches zero, then 
the process can no longer access the semaphore; and if there are no 
other processes with access to the semaphore, the resources allocated 
for the semaphore are freed. 
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RESTRICTIONS/WARNINGS 


@ [fan attempt is made to close an event semaphore on which another 
thread is blocked in the current process, ERROR_SEM_BUSY is re- 
turned. 





DosCreateEventSem Semaphores 





Creates a private or shared event semaphore. 


SYNTAX 


APIRET DosCreateEventSem(PSZ pszSemName, PHEV phevSemaphore, 
ULONG ulfAtinbutes, BOOL32 /32State) 


PARAMETERS 


pszSemName - input 

A pointer to a null-terminated string containing the name of the sem- 
aphore. The name must have the prefix \SEM32\, must not be longer 
than 255 characters, and must conform to the naming conventions of 
the file system. If pszSemName is NULL, then the semaphore is consid- 
ered unnamed. All named semaphores are considered shared. 
phevSemaphore - output 

An address of an HEV that will receive the handle of the newly created 
semaphore. 

ulfAttributes - input 

Only one flag may be specified for this parameter: DO_SEM_SHARED. 
If set, the semaphore is considered to be an unnamed shared sema- 
phore. This value is checked only if pszSemName equals NULL. 
f2State - input 

Specify one of the following state options: 


States Description 


FALSE Q The initial state of the semaphore is set (the post count is 
zero). Any thread that waits on this semaphore will block. 


TRUE 1 The initial state of the semaphore is posted (the post 
count is set to one). 
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RETURNS 
0 NO_ERROR 123 ERROR INVALID _ 
NAME 
8 ERROR NOT ENOUGH _ 285 ERROR DUPLICATE _ 
MEMORY NAME 
87 ERROR INVALID PARAMETER 290 ERROR TOO MANY, 
HANDLES 
OTHER INFO 
Include file: bsedos.h Define: INCL. DOSSEMAPHORES 
Ordinal: 324 DLL: DOSCALLS 
SEE ALSO 


DosCloseEventSem -306, DosOpenEventSem -308, 
DosPostEventSem -309, DosQueryEventSem -310, 
DosResetEventSem -311, DosWaitEventSem -312 


NOTES 


The process that creates a semaphore doesn’t need to open it to use it. 
The semaphore is accessible to all threads of the calling process. 


RESTRICTIONS/WARNINGS 


@ If the name specified in pszSemName is rejected by the file system, 
ERROR INVALID NAME is returned. 

e@ If the name specified for the semaphore is already in use, then ER- 
ROR_DUPLICATE_NAME is returned. 

@ If the number of semaphores exceeds the system limit of 65536, 
then ERROR TOO_MANY HANDLES is returned. 





DosOpenEventSem Semaphores 


Obtains access to a shared event semaphore for the calling process. 


SYNTAX 
APIRET DosOpenEventSem (PSZ pszSemName, PHEV phevSemaphore) 


PARAMETERS 


pszSemName - input 
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A pointer to a null-terminated string containing the name of the event 
semaphore to gain access to. If NULL, then the semaphore to obtain 
access to will be opened by its handle (see phevSemaphore). 
phevSemaphore - input/output 

On input, the address of an event semaphore handle. If pszSemName is 
not NULL, then this value must be NULL, otherwise ERROR_IN- 
VALID_PARAMETER is returned. On output, the address of an HEV 
containing the handle of the opened event semaphore. 


RETURNS 

0 NO_ERROR 123 ERROR INVALID _ 
NAME 

6 ERROR INVALID HANDLE 187 ERROR SEM NOT_ 
FOUND 

8 ERROR NOT ENOUGH _ 291 ERROR TOO _MANY_ 

MEMORY OPENS 

87 ERROR INVALID PARAMETER 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 

Ordinal: 325 DLL: DOSCALLS 

SEE ALSO 


DosCloseEventSem -306, DosCreateEventSem -307, 
DosPostEventSem -309, DosQueryEventSem -310, 
DosResetEventSem -311, DosWaitEventSem -312 


NOTES 


It is not necessary for the process that created the semaphore to use 
this call. 

This call increases the usage count for the semaphore by one. If 
the usage count for a semaphore exceeds 65535, the call will return 
ERROR_TOO_MANY_OPENS. 





DosPostEventSem Semaphores 


Posts an event semaphore. 


SYNTAX 
APIRET DosPostEventSem (HEV hevSemaphore) 
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PARAMETERS 
hevSemaphore - input 
The handle of the event semaphore to post. 


RETURNS 

0 NO_ERROR 298 ERROR TOO_MANY_ 
POSTS 

6 ERROR INVALID HANDLE 299 ERROR _ALREADY_ 
POSTED 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 

Ordinal: 328 DLL: DOSCALLS 

SEE ALSO 


DosCloseEventSem -306, DosCreateEventSem -307, 
DosOpenEventSem -308, DosQueryEventSem -310, 
DosResetEventSem -311, DosWaitEventSem -312 


NOTES 


When an event semaphore is posted, all threads blocked on that sema- 
phore are released. 

This call increases the post count of the semaphore by one. If the 
semaphore has already been posted, then the call will return ER- 
ROR_ALREADY_POSTED and increase the post count by one. If the 
call increases the post count higher than 65535, ERROR_TOO_ 
MANY_POSTS is returned. Use DosQueryEventSem to determine the 
post count of an event semaphore. 





@® DosQueryEventSem Semaphores 


Returns the post count of an event semaphore. 


SYNTAX 

APIRET DosQueryEventSem (HEV hevSemaphore, PULONG 
pulPostCount) 

PARAMETERS 


hevSemaphore - input 
The handle of the event semaphore to query. 


Semaphores 311 


pulPostCount - output 

A pointer to a ULONG that will receive the post count of the semaphore. 
This value is the number of DosPostEventSem calls issued against the 
semaphore since the last time the event semaphore was reset. 


RETURNS 

0 NO_ERROR 87 ERROR INVALID _ 
PARAMETER 

6 ERROR_INVALID HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 

Ordinal: 330 DLL: DOSCALLS 

SEE ALSO 


DosCloseEventSem -306, DosCreateEventSem -307, 
DosPostEventSem -309, DosResetEventSem -311, 
DosWaitEventSem -312 


NOTES 


The calling process must have access to the semaphore before issuing 
this call. 





DosResetEventSem Semaphores 





Resets the post count of an event semaphore. 


SYNTAX 

APIRET DosResetEventSem (HEV hevSemaphore, PULONG 
pulPostCount) 

PARAMETERS 


hevSemaphore - input 

The handle of the event semaphore to reset. 

pulPostCount - output 

A pointer to a ULONG that will receive the semaphore’s post count 
since the last time it was reset. You cannot pass NULL for this parame- 
ter even if you do not care about the post count. 


RETURNS 


0 NO_ERROR 300 ERROR_ALREADY_RESET 
6 ERROR_INVALID_ HANDLE 
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OTHER INFO 

Include file: bsedos.h Define: INCL. DOSSEMAPHORES 
Ordinal: 327 DLL: DOSCALLS 

SEE ALSO 


DosCloseEventSem -306, DosCreateEventSem -307, DosOpenEvent- 
Sem -308, DosPostEventSem -309, DosWaitEventSem -312 


NOTES 


Unless the calling process created the semaphore, it must first obtain 
access to it (using DosOpenEventSem) before issuing this call, other- 
wise ERROR _ INVALID HANDLE is returned. 

After this call is issued, any thread that issues a DosWaitEventSem 
against this semaphore will block until it is posted. 





DosWaitEventSem Semaphores 


Causes the current thread to block until the specified event sema- 
phore is posted. 


SYNTAX 
APIRET DosWaitEventSem (HEV hevSemaphore, ULONG wulTimeOut) 


PARAMETERS 

hevSemaphore - input 

The handle of the event semaphore to block on. 

ulTimeOut - input 

The amount of time, in milliseconds, for the thread to wait before the 
call returns. The following values are also valid: 


Time-out options Description 


SEM_IMMEDIATE RETURN 0 The call will return immediately 
regardless of whether the 
semaphore is posted. 


SEM_INDEFINITE_WAIT -1_ The call will block indefinitely until 
the semaphore is posted. 
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RETURNS 

0 NO_ERROR 95 ERROR INTERRUPT 

6 ERROR INVALID HANDLE 640 ERROR TIMEOUT 

8 ERROR NOT_ENOUGH_MEMORY 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSSEMAPHORES 
Ordinal: 329 DLL: DOSCALLS 

SEE ALSO 


DosCloseEventSem -306, DosCreateEventSem -307, 
DosOpenEventSem -308, DosPostEventSem -309, 
DosResetEventSem -311, WinWaitEventSem 


NOTES 


Event semaphores are edge-triggered, so if the semaphore is posted 
and reset before the calling thread gets a chance to run, it will still act 
as if the semaphore is posted. If the semaphore is already posted be- 
fore issuing this call, it will return immediately. Note: Event sema- 
phores as a group in a mutex semaphore are level-triggered. 

If the call returns because the time-out value was exceeded, then 
ERROR_ TIMEOUT is returned. 

Unless the calling process created the semaphore, it must first ob- 
tain access to it before issuing this call, otherwise ERROR_INVALID_ 
HANDLE is returned. 

If the call is interrupted due to an exception, or a no-wait I/O 
event occurred, ERROR INTERRUPT is returned. 


RESTRICTIONS/WARNINGS 


@ When blocking on an event semaphore in a PM thread, WinWait- 
EventSem should be used instead of DosWaitEventSem. This will al- 
low the message queue for the PM thread to continue processing 
while blocked on the event semaphore. 


Mutual Exclusion Semaphore Functions 





DosCloseMutexSem decrements the usage count of a mutex sema- 
phore. If the usage count equals zero, then the semaphore is deleted 
from the system (pg. 314). 
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DosCreateMutexSem creates a private or shared mutex semaphore 
(pg. 315). 

DosOpenMutexSem obtains access, for the calling process, to a shared 
mutex semaphore (pg. 316). 

DosQueryMutexSem returns the process ID and thread ID of the 
owner of a mutex semaphore, as well as the request count (pg. 318). 
DosReleaseMutexSem releases ownership of a mutex semaphore 
(pe. 219). 

DosRequestMutexSem blocks the calling thread until ownership of 
the specified mutex semaphore is gained (pg. 320). 





DosCloseMutexSem Semaphores 





Decrements the usage count of the specified mutex semaphore and/ 
or frees the semaphore. 


SYNTAX 
APIRET DosCloseMutexSem (HMTX hmixSemaphore) 


PARAMETERS 


hmtxSemaphore - input 
The handle of the mutex semaphore whose usage count will be decre- 
mented by one. 


RETURNS 


0 NO_ERROR 301 ERROR_SEM_BUSY 
6 ERROR_INVALID_ HANDLE 


OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 
Ordinal: 300 DLL: DOSCALLS 

SEE ALSO 


DosCreateMutexSem -315, DosOpenMutexSem -316, 
DosQueryMutexSem -318, DosReleaseMutexSem -319, 
DosRequestMutexSem -320 


NOTES 


For unnamed, nonshared semaphores, this call frees the semaphore 
resource from the system. 
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For unnamed shared semaphores, this call discontinues access to 
the semaphore for the calling process, and if there are no other 
processes accessing the semaphore, the semaphore is freed from the 
system. 

For named semaphores, this call will decrement the usage count 
of the target semaphore by one. If the usage count reaches zero, then 
the process can no longer access the semaphore; and if there are no 
other processes with access to the semaphore, the resources allocated 
for the semaphore are freed. 


RESTRICTIONS/WARNINGS 


e Ifan attempt is made to close a mutex semaphore on which another 
thread is blocked in the current process, ERROR_SEM_BUSY is re- 
turned. 





DosCreateMutexSem Semaphores 





Creates a private or shared mutex semaphore. 


SYNTAX 


APIRET DosCreateMutexSem (PSZ pszSemName, PHMTX phmtxSema- 
phore, ULONG ulfAtiributes, BOOL32 
[22Staie) 


PARAMETERS 


pszSemName - input 

A pointer to a null-terminated string containing the name of the sem- 
aphore. The name must have the prefix \SEM32\, must not be longer 
than 255 characters, and must conform to the naming conventions of 
the file system. If pszSemName is NULL, then the semaphore is consid- 
ered unnamed. All named semaphores are considered shared. 
phmtxSemaphore - output 

An address of an HMT*X that will receive the handle of the newly cre- 
ated semaphore. 

ulfAttributes - input 

Only one flag may be specified for this parameter: DO_SEM_SHARED. 
If set, the semaphore is considered to be an unnamed shared sema- 
phore. This value is checked only if pszSemName equals NULL. 
f32State - input 

Specify one of the following state options: 
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States Description 


FALSE Q The initial state of the semaphore is unowned. 
Threads waiting on this semaphore will not block. 


TRUE 1 The initial state of the semaphore is owned. Threads 
waiting on this semaphore will block. 


RETURNS 

0 NO_ERROR 123 ERROR INVALID _ 
NAME 

8 ERROR NOT_ENOUGH_ 285 ERROR DUPLICATE _ 

MEMORY NAME 

87 ERROR INVALID PARAMETER 290 ERROR _ TOO_MANY_ 
HANDLES 

OTHER INFO 

Include file: bsedos.h Define: , INCL DOSSEMAPHORES 

Ordinal: 331 DLL: DOSCALLS 

SEE ALSO 


DosCloseMutexSem -314, DosOpenMutexSem -316, 
DosQueryMutexSem -318, DosReleaseMutexSem -319, 
DosRequestMutexSem -320 


NOTES 


The process that creates a semaphore doesn’t need to open it to use it. 
The semaphore is accessible to all threads of the calling process. 


RESTRICTIONS/WARNINGS 


@ If the name specified in pszSemName is rejected by the file system, 
ERROR INVALID NAME is returned. 

@ If the name specified for the semaphore is already in use, then ER- 
ROR DUPLICATE_NAME is returned. 

@ If the number of semaphores exceeds the system limit of 65536, 
then ERROR _TOO_MANY HANDLES is returned. 





DosOpenMutexSem Semaphores 


Obtains access to a shared mutex semaphore for the calling process. 
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SYNTAX 

APIRET DosOpenMutexSem (PSZ pszSemName, PHMTX 
phmtxSemaphore) 

PARAMETERS 


pszSemName - input 

A pointer to a null-terminated string containing the name of the mu- 
tex semaphore to gain access to. If NULL, then the semaphore to ob- 
tain access to will be opened by its handle (see phmtxSemaphore). 
phmtxSemaphore - input/output 

On input, the address of a mutex semaphore handle. If pszSemName 1s 
not NULL, then this value must be NULL, otherwise ERROR_IN- 
VALID_PARAMETER is returned. On output, the address of an 
HMT*X contains the handle of the opened mutex semaphore. 


RETURNS 

0 NO_ERROR 105 ERROR_SEM_OWNER_ 
DIED 

6 ERROR INVALID HANDLE 123 ERROR_ INVALID _ 
NAME 

8 ERROR NOT_ENOUGH_ 187 ERROR SEM NOT_ 

MEMORY FOUND 

87 ERROR INVALID PARAMETER 291 ERROR TOO _MANY_ 
OPENS 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSSEMAPHORES 

Ordinal: 332 DLL: DOSCALLS 

SEE ALSO 


DosCloseMutexSem -314, DosCreateMutexSem -315, 
DosQueryMutexSem -318, DosReleaseMutexSem -319, 
DosRequestMutexSem -320 


NOTES 


It is not necessary for the process that created the semaphore to use 
this call. 

This call increases the usage count for the semaphore by one. If 
the usage count for a semaphore exceeds 65535, the call will return 
ERROR_TOO_MANY_OPENS. 
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If the process that owns the semaphore dies before releasing it, 
ERROR_SEM_OWNER_DIED is returned. You may use DosQuery- 
MutexSem to determine which process died without releasing the sem- 
aphore. 





DosQueryMutexSem Semaphores 


Returns the process ID and thread ID of the mutex semaphore owner, 
as well as the request count. 


SYNTAX 


APIRET DosQueryMutexSem (HMTX hmixSemaphore, PPID ppidSem- 
Owner, PTID ptidSemOwner, PULONG 
pulRequestCount) 


PARAMETERS 


hmtxSemaphore - input 

The handle of the mutex semaphore to query. 

ppidSemOwner - output 

The address of a PID that will receive the process ID of the current 
owner of the mutex semaphore. If the call returns ERROR_SEM_ 
OWNER_DIED, then the process ID returned did not release the sem- 
aphore before terminating. 

ptidSemOwner - output 

The address of a TID that will receive the thread ID of the current 
owner of the mutex semaphore. 

pulRequestCount - output 

The address of a ULONG that will receive the request count of the mu- 
tex semaphore. The request count indicates the number of requests 
for the semaphore minus the number of releases of the semaphore by 
the owning thread. If the semaphore is currently unowned, this value 
is zero. If this call returns ERROR_SEM OWNER _ DIED, then this 
value contains the request count of the dead owner. 


RETURNS 

0 NO_ERROR 87 ERROR_INVALID_ 
PARAMETER 

6 ERROR _INVALID_HANDLE 105 ERROR_SEM_OWNER_ 


DIED 
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OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 
Ordinal: 3360 DLL: DOSCALLS 

SEE ALSO 


DosCloseMutexSem -314, DosCreateMutexSem -315, 
DosOpenMutexSem -316, DosReleaseMutexSem -319, 
DosRequestMutexSem -320 


NOTES 


If ERROR_SEM OWNER _ DIED is returned, then the information in 
ppidSemOwner, ptidSemOwner, and pulRequestCount refers to the dead 
owner. 


RESTRICTIONS/WARNINGS 


@ Processes must first obtain access to the semaphore before execut- 
ing this call, otherwise ERROR_INVALID_HANDLE is returned. 





DosReleaseMutexSem Semaphores 





Releases ownership of a mutex semaphore. 


SYNTAX 
APIRET DosReleaseMutexSem (HMTX hmtxSemaphore) 


PARAMETERS 


hmtxSemaphore - input 
The handle of the mutex semaphore to be released. 


RETURNS 

0 NO_ERROR 288 ERROR NOT OWNER 
6 ERROR_INVALID HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSSEMAPHORES 


Ordinal: 335 DLL: DOSCALLS 
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SEE ALSO 


DosCloseMutexSem -314, DosCreateMutexSem -315, 
DosOpenMutexSem -316, DosQueryMutexSem -318, 
DosRequestMutexSem -320 


NOTES 


This call reduces the usage count of the semaphore by one. If the us- 
age count drops to zero, the ownership of the semaphore will pass to 
another thread that is blocked on the semaphore. 


RESTRICTIONS/WARNINGS 


@ This call can only be issued by the current owner of the semaphore, 
otherwise ERROR NOT_OWNER is returned. 





DosRequestMutexSem Semaphores 


{ 


Blocks the calling thread until ownership of the mutex semaphore is 
obtained. 


SYNTAX 

APIRET DosRequestMutexSem (HMTX hmixSemaphore, ULONG 
ulTimeOut) 

PARAMETERS 


hmtxSemaphore - input 

The handle of the mutex semaphore whose ownership is requested. 
ulTimeOut - input 

The time-out value, in milliseconds, before the call returns. The fol- 
lowing values may also be specified: 


Time-out Options Description 

SEM_ IMMEDIATE RETURN 0 The call is to return immediately 
regardless of whether ownership is 
obtained. 

SEM_INDEFINITE_WAIT -1_ The call will block indefinitely until 


ownership of the semaphore is 
obtained. 
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RETURNS 

0 NO_ERROR 103 ERROR_TOO_MANY_ 
SEM_REQUESTS 

6 ERROR_INVALID HANDLE 105 ERROR_SEM_OWNER_ 


DIED 
95 ERROR INTERRUPT 640 ERROR TIMEOUT 
OTHER INFO 
Include file: bsedos.h Define: INCL DOSSEMAPHORES 
Ordinal: 334 DLL: DOSCALLS 
SEE ALSO 


DosCloseMutexSem -314, DosCreateMutexSem -315, 
DosOpenMutexSem -316, DosQueryMutexSem -318, 
DosReleaseMutexSem -319, 


NOTES 


If the semaphore times-out (or ulTimeOut = SEM_IMMEDIATE_RE- 
TURN) and returns without obtaining ownership of the semaphore, 
ERROR TIMEOUT is returned. 

Ownership of a semaphore that has multiple threads requesting it 
is determined by the priority and the ordering of the requests by those 
threads. The thread with the highest priority will receive ownership of 
the semaphore first. If the threads have the same priority, then owner- 
ship is granted FIFO. 


RESTRICTIONS/WARNINGS 


e@ A thread must release ownershio of a mutex semaphore before ter- 
minating, otherwise the next thread that requests the semaphore 
will get an ERROR_SEM_OWNER_DIED return code. 

@ Once ownership of the semaphore is obtained, this call will incre- 
ment the usage count of the semaphore by one. Requests for a mu- 
tex semaphore can be nested, but if the usage count exceeds 65535, 
ERROR_TOO_MANY_SEM_REQUESTS is returned. 

@ The calling process must obtain access to the semaphore before is- 
suing this call, otherwise ERROR_INVALID_ HANDLE is returned. 

@ If an external event occurs that causes the call to unblock (such as 
an exception is generated, or a no wait I/O request has just com- 
pleted) while the thread is waiting on the semaphore, ERROR_IN- 
TERRUPT is returned. 
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Muxwait Semaphore Functions 





DosAddMuxWaitSem adds either mutex or an event semaphore to a 
muxwait list (pg. 322). 

DosCloseMuxWaitSem closes a muxwait semaphore in the case of a 
private semaphore, or decrements the usage count in the case of a 
shared semaphore (pg. 323). 

DosCreateMuxWaitSem creates a private or shared muxwait sema- 
phore (pg. 325). 

DosDeleteMuxWaitSem removes an event or mutex semaphore from 
the semaphore record list of the specified muxwait semaphore (pg. 
B27): 

DosOpenMuxWaitSem obtains access for the current process to a 
shared muxwait semaphore (pg. 328). 

DosQueryMuxWaitSem returns the semaphore records of the speci- 
fied muxwait semaphore (pg. 330). 

DosWaitMuxWaitSem blocks the calling thread until the specified 
muxwait semaphore clears (pg. 331). 





@ DosAddMuxWaitSem Semaphores 





Adds an event or mutex semaphore to a muxwait semaphore list. 


SYNTAX 


APIRET DosAddMuxWaitSem(HMUX hmuxSemaphore, 
PSEMRECORD pSemaphoreRecord) 


PARAMETERS 


hmuxSemaphore - input 

The handle of a muxwait semaphore. 

pSemaphoreRecord - input 

The address of a SEMRECORD that will be added to the muxwait sem- 
aphore list. 


RETURNS 


0 NO_ERROR 100 ERROR_TOO_MANY_ 
SEMAPHORES 

6 ERROR_INVALID_ HANDLE 105 ERROR_SEM_OWNER_ 
DIED 
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8 ERROR NOT ENOUGH __ 284 ERROR DUPLICATE _ 
MEMORY HANDLE 

87 ERROR INVALID PARAMETER 292 ERROR WRONG_TYPE 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 

Ordinal: 341 DLL: DOSCALLS 

SEE ALSO 


DosCloseMuxWaitSem -323, DosCreateMuxWaitSem -325, 
DosDeleteMuxWaitSem -327, DosOpenMuxWaitSem -328, 
DosQueryMuxWaitSem -330, DosWaitMuxWaitSem -331 


RESTRICTIONS/WARNINGS 


If an attempt is made to add a semaphore of a different type than 
what is already in the list, ERROR_WRONG_TYPE is returned. 

If an attempt is made to add more than 64 semaphores to a muxwait 
list, ERROR TOO MANY SEMAPHORES is returned. 

If an attempt is made to add a semaphore to the list of a shared 
muxwait semaphore, then each process that has obtained access to 
the muxwait semaphore must have access to that semaphore, other- 
wise any thread blocked on the muxwait semaphore will be un- 
blocked and return an error of ERROR INVALID HANDLE. The 
DosAddMuxWaitSem call will not return an error in this case. Any 
process that needs to use the muxwait semaphore from this point on 
will need to obtain access to the newly added semaphore first, oth- 
erwise any calls concerning the muxwait semaphore for the process 
will return ERROR INVALID HANDLE. 

A thread that is waiting on a muxwait semaphore and returns for the 
reasons just specified can use DosQueryMuxWaitSem to determine 
which semaphores are in the list, and then call the appropriate 
query for the target semaphore to determine if the process has ac- 
cess. If not, the appropriate open call can be made against the target 
semaphore. 





DosCloseMuxWaitSem Muxwait Semaphores 


Decrements the usage count of a muxwait semaphore and/or frees the 
semaphore. 
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SYNTAX 
APIRET DosCloseMuxWaitSem (HMUX hmuxSemaphore) 


PARAMETERS 


hmuxSemaphore - input 
The handle of the muxwait semaphore whose usage count is to be 
decremented. 


RETURNS 


0 NO_ERROR 301 ERROR _SEM_BUSY 
6 ERROR INVALID HANDLE 


OTHER INFO 


Include file: bsedos.h Define: INCL_DOSSEMAPHORES 
Ordinal: 339 DLL: DOSCALLS 


SEE ALSO 


DosAddMuxWaitSem -322, DosCreateMuxWaitSem -325, 
DosDeleteMuxWaitSem -327, DosOpenMuxWaitSem -328, 
DosQueryMuxWaitSem -330, DosWaitMuxWaitSem -331 


NOTES 


For unnamed, nonshared semaphores, this call frees the semaphore 
resource from the system. 

For unnamed shared semaphores, this call discontinues access to 
the semaphore for the calling process, and if there are no other 
processes accessing the semaphore, the semaphore is freed from the 
system. 

For named semaphores, this call will decrement the usage count 
of the target semaphore by one. If the usage count reaches zero, then 
the process can no longer access the semaphore; and if there are no 
other processes with access to the semaphore, the resources allocated 
for the semaphore are freed. 


RESTRICTIONS/WARNINGS 


e If an attempt is made to close a muxwait semaphore on which an- 
other thread is blocked in the current process, ERROR_SEM_BUSY 
is returned. 
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@ DosCreateMuxWaitSem Semaphores 





Creates a private or shared muxwait semaphore. 


SYNTAX 


APIRET DosCreateMuxWaitSem (PSZ pszSemName, PHMUX phmux- 
Semaphore, ULONG ulNumberOf- 
Records, PPEMRECORD pSemRecord, 
ULONG wlfAttnbutes) 


PARAMETERS 


pszSemName - input 

A pointer to a null-terminated string containing the name of the sem- 
aphore. The name must have the prefix \SEM32\, must not be longer 
than 255 characters, and must conform to the naming conventions of 
the file system. If pszSemName is NULL, then the semaphore is consid- 
ered unnamed. All named semaphores are considered shared. 
phmuxSemaphore - output 

The address of an HMUX that will receive the handle of the newly cre- 
ated semaphore. 

ulNumberOfRecords - input 

The number of records that pSemRecord points to. No more than 64 
records can be in a muxwait list. 

pSemRecord - input 

A pointer to a buffer containing an array of SEMRECORD structures 
to be added to the muxwait list. 

ulfAttributes - input 

Specify the following options: 


Attributes Description 


DC_SEM_SHARED Ox01 ‘The semaphore is shared. This flag is 
checked only if pszSemName is NULL. For 
unnamed semaphores, the handle must be 
communicated to other processes via some 
form of interprocess communication. 


DCMW_WAIT_ANY Ox02 The semaphore is to clear (unblock) if any 
of the semaphores in the list either post 
(event semaphores) or release (mutex 
semaphores). 
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DCMW_WAIT_ALL 0x04 The semaphore is to clear (unblock) only 
if all of the semaphores in the list are 
either posted (event semaphores) or 
released (mutex semaphores). 


RETURNS 
0 NO ERROR 123 ERROR INVALID _ 
NAME 
6 ERROR INVALID HANDLE 284 ERROR DUPLICATE _ 
HANDLE 
8 ERROR NOT _ENOUGH_ 285 ERROR DUPLICATE _ 
MEMORY NAME 
87 ERROR INVALID _ 290 ERROR TOO _MANY_ 
PARAMETER HANDLES 
100 ERROR _TOO_MANY_ 292 ERROR WRONG_TYPE 
SEMAPHORES 
105 ERROR SEM OWNER _DIED 
OTHER INFO 
Include file: bsedos.h Define: INCL. _DOSSEMAPHORES 
Ordinal: 337 DLL: DOSCALLS 
SEE ALSO 


DosAddMuxWaitSem -322, DosCloseMuxWaitSem -323, 
DosDeleteMuxWaitSem -327, DosOpenMuxWaitSem -328, 
DosQueryMuxWaitSem -330, DosWaitMuxWaitSem -331 


NOTES 


The process that creates a semaphore doesn’t need to open it to use it. 
The semaphore is accessible to all threads of the calling process. 

Creating a muxwait semaphore sets the usage count for that sem- 
aphore to one. 


RESTRICTIONS/WARNINGS 


e@ If the muxwait semaphore is shared, then only shared semaphores 
can be included in the muxwait list. If the muxwait semaphore is pri- 
vate, then the list can contain both shared and private semaphores. 
Muxwait semaphores cannot be added to a muxwait list. If any of 
these rules are violated, ERROR WRONG_TYPE is returned. 

@ If the muxwait semaphore is to be made up of mutex semaphores, 
then the mutex semaphores must not have dead owners (that is, the 
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owner of the semaphore died before releasing it), otherwise ER- 
ROR_ SEM OWNER _DIED is returned. 

For muxwait semaphores that include shared semaphores, the call- 
ing process must have access to those semaphores, otherwise ER- 
ROR_INVALID HANDLE is returned. 

If the name specified in pszSemName is rejected by the file system, 
ERROR INVALID NAME is returned. 

If the name specified for the semaphore is already in use, then ER- 
ROR DUPLICATE_NAME is returned. 

If the number of semaphores exceeds the system limit of 65536, 
then ERROR _ TOO MANY HANDLES is returned. 

If the value of ulNumberOfRecords is greater than 64, then ER- 
ROR_ TOO_MANY SEMAPHORES is returned. 





DosDeleteMuxWaitSem Semaphores 





Deletes a semaphore record from a muxwait list. 


SYNTAX 

APIRET DosDeleteMuxWaitSem (HMUX hmuxSemaphore, HSEM 
hsemSemaphore) 

PARAMETERS 


hmuxSemaphore - input 

The handle of the muxwait semaphore. 

hsemSemaphore - input 

The handle of the event or mutex semaphore whose record is to be 
deleted from the muxwait semaphore list. The handle passed must be 
cast from either an HMTX or an HEV to an HSEM. 


RETURNS 

0 NO_ERROR 286 ERROR EMPTY, 
MUXWAIT 

6 ERROR INVALID HANDLE 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSSEMAPHORES 


Ordinal: 342 DLL: DOSCALLS 
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SEE ALSO 


DosAddMuxWaitSem -322, DosCloseMuxWaitSem -323, 
DosCreateMuxWaitSem -325, DosOpenMuxWaitSem -328, 
DosQueryMuxWaitSem -330, DosWaitMuxWaitSem -331 


NOTES 


Only processes that have obtained access to the muxwait semaphore 
can delete semaphore records from the list. 

If the semaphore that is deleted from the list is the last one in the 
list, any threads blocked on the muxwait semaphore are unblocked. 
Also, threads that are blocked on a muxwait semaphore that was cre- 
ated with the DOCMW_WAIT_ALL flag will unblock if the semaphore 
deleted is the only semaphore that was left to release (mutex sema- 
phores) or post (event semaphores). 





DosOpenMuxWaitSem Semaphores 


Obtains access to a shared muxwait semaphore for the calling process. 


SYNTAX 

APIRET DosOpenMuxWaitSem (PSZ pszSemName, PHMUX 
phmuxSemaphore) 

PARAMETERS 


pszSemName - input 

A pointer to a null-terminated string containing the name of the 
muxwait semaphore to obtain access to. If NULL, then the semaphore 
to obtain access to is specified in phmuxSemaphore. 

phmuxSemaphore - input/output 

On input, the address of a muxwait semaphore handle. If pszSemName 
is not NULL, then this value must be NULL, otherwise ERROR_IN- 
VALID_PARAMETER is returned. On output, the address of an 
HMUxX containing the handle of the opened muxwait semaphore. 


RETURNS 

0 NO_ERROR 105 ERROR_SEM_OWNER_ 
DIED 

6 ERROR_INVALID_HANDLE 123 ERROR_INVALID_ 


NAME 
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8 ERROR NOT_ENOUGH_. 187 ERROR SEM NOT_ 
MEMORY FOUND 

87 ERROR INVALID PARAMETER 291 ERROR TOO_MANY_ 

OPENS 

OTHER INFO 

Include file: bsedos.h Define: INCL. _DOSSEMAPHORES 

Ordinal: 338 DLL: DOSCALLS 

SEE ALSO 


DosAddMuxWaitSem -322, DosCloseMuxWaitSem -323, 
DosCreateMuxWaitSem -325, DosDeleteMuxWaitSem -327, 
DosQueryMuxWaitSem -330, DosWaitMuxWaitSem -331 


NOTES 


It is not necessary for the process that created the semaphore to use 
this call. | 

This call increases the usage count for the semaphore by one. If 
the usage count for a semaphore exceeds 65535, the call will return 
ERROR_TOO_MANY_OPENS. 

If the muxwait semaphore contains a list of mutex semaphores, it 
is possible that one of those semaphores may be owned by a process 
that has died without releasing it. In this case, the first attempt to open 
the muxwait semaphore will be successful, but subsequent requests will 
return ERROR_SEM_OWNER_DIED. After issuing the first open re- 
quest, you may then use DosQueryMuxWaitSem to determine the list 
of mutex semaphores in the muxwait list, and then call DosQuery- 
MutexSem on each semaphore. If the call returns ERROR_ SEM_ 
OWNER_DIED, the semaphore should be closed (see DosClose- 
MutexSem, page xxx) and the semaphore should be deleted from the 
muxwait list (since semaphore handles can be reused). 


RESTRICTIONS/WARNINGS 


e@ A process that intends to open a mutex semaphore must first obtain 
access to each semaphore in the muxwait list before opening the 
muxwait semaphore, otherwise ERROR_INVALID_HANDLE is re- 
turned. 
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@ DosQueryMuxWaitSem Semaphores 


Returns the semaphore records of the specified muxwait semaphore. 


SYNTAX 

APIRET DosQueryMuxWaitSem (HMUX hmuxSemaphore, PULONG 
pulSemRecords, PPEMRECORD 
pSemRecord, PULONG pflAtiributes) 

PARAMETERS 


hmuxSemaphore - input 

The handle of the muxwait semaphore to query. 

pulSemRecords - input/output 

On input, the address of a ULONG that contains the number of 
records that can be returned in the semaphore list pointed to by 
pSemRecord. On output, the actual number of records retrieved. If the 
buffer specified by pSemRecord is too small, then ERROR_PARAM_ 
TOO_SMALL is returned, and this value indicates the total number of 
records in the muxwait semaphore list. 

pSemRecord - output 

The pointer to a buffer that will receive the semaphore records. 
pflAttributes - output 

The attributes that were specified on the DosCreateMuxWait call: 


Attributes Description 
DC_SEM_ SHARED 0x01 The semaphore shared. 
DCMW_WAIT_ANY 0x02 The semaphore will clear (unblock) if any 


of the semaphores in the list either post 
(event semaphores) or release (mutex 
semaphores). 


DCMW_WAIT_ALL 0x04 The semaphore will clear (unblock) only 
if all of the semaphores in the list are 
either posted (event semaphores) or 
released (mutex semaphores). 


RETURNS 


0 NO_ERROR 87 ERROR_INVALID_ 
PARAMETER 


Semaphores 331 


6 ERROR INVALID HANDLE 105 ERROR SEM OWNER_ 
DIED 

8 ERROR NOT ENOUGH _ 289 ERROR PARAM TOO _ 
MEMORY SMALL 

OTHER INFO 

Include file: bsedos.h Define: INCL. _DOSSEMAPHORES 

Ordinal: 343 DLL: DOSCALLS 

SEE ALSO 


DosAddMuxWaitSem -322, DosCloseMuxWaitSem -323, 
DosCreateMuxWaitSem -325, DosDeleteMuxWaitSem -327, 
DosOpenMuxWaitSem -328, DosWaitMuxWaitSem -331 


RESTRICTIONS/WARNINGS 


@ The process must first obtain access to the semaphore before issuing 
this call, otherwise ERROR INVALID HANDLE is returned. 

@ If the muxwait semaphore contains a list of mutex semaphores it is 
possible that one of those semaphores may be owned by a process 
that has died without releasing it. In this case, use DosQuery- 
MutexSem on each semaphore. If the call returns ERROR_SEM_ 
OWNER_DIED, the semaphore should be closed using DosClose- 
MutexSem, and the semaphore should be deleted from the muxwait 
list (since semaphore handles can be reused). 





DosWaitMuxWaitSem Semaphores 





Blocks the calling thread until the specified muxwait semaphore 
clears. 


SYNTAX 


APIRET DosWaitMuxWaitSem (HMUX hmuxSemaphore, ULONG 
ullimeOut, PULONG pulUserField) 


PARAMETERS 


hmuxSemaphore - input 

The handle of the muxwait semaphore to block on. 

ulTimeOut - input 

The amount of time, in milliseconds, for the thread to wait before the 
call returns. The following values are also valid: 
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Time-out Options Description 


SEM_IMMEDIATE_RETURN 0 The call will return immediately 
regardless of whether the semaphores are 
posted or released. 


SEM_INDEFINITE_WAIT -1_ The call will block indefinitely until all 
the semaphores in the list are posted or 
released. 


pulUserField - output 

A pointer to a ULONG that will receive the value of the user field (part 
of the SEMRECORD structure). If the semaphore was created with the 
DCMW_WAIT_ANY flag, then this value will contain the user field of 
the semaphore that was posted or released. If the semaphore was cre- 
ated with the DCMW_WAIT_ALL flag, then this value will contain the 
user field of the last semaphore that was posted or released. If the 
thread didn’t block, this value will contain the user field of the last 
semaphore record in the muxwait list. 


RETURNS 
0 NO_ERROR 105 ERROR SEM OWNER. 
DIED 
6 ERROR INVALID HANDLE 286 ERROR EMPTY. 
MUXWAIT 
8 ERROR NOT ENOUGH _ 287 ERROR MUTEX_ 
MEMORY OWNED 
87 ERROR INVALID PARAMETER 292 ERROR _WRONG_TYPE 
95 ERROR INTERRUPT 640 ERROR TIMEOUT 
103 ERROR_TOO_MANY_SEM_REQUESTS 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSSEMAPHORES 
Ordinal: 340 DLL: DOSCALLS 
SEE ALSO 


DosAddMuxWaitSem -322, DosCloseMuxWaitSem -323, 
DosCreateMuxWaitSem -325, DosDeleteMuxWaitSem -327, 
DosOpenMuxWaitSem -328, DosQueryMuxWaitSem -330, 
Win WaitMuxWaitSem 
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NOTES 


Muxwait semaphores are edge-triggered even if they consist of event 
semaphores. Therefore, if a thread is waiting on a muxwait semaphore 
(with the DOMW_WAIT_ALL option) that consists of five event sema- 
phores, and four of the five semaphores post, but then the first sema- 
phore gets reset before the last semaphore is posted, the thread must 
again wait for the first semaphore to post. 

If the thread is waiting for all the mutex semaphores of a muxwait 
semaphore to release, then ownership of those mutex semaphores 
only occurs after all of the semaphores are released. 

If the thread is waiting for any mutex semaphore of a muxwait 
semaphore to release, then the thread will only receive ownership of 
the first mutex semaphore that is released. 

If any of the mutex semaphores in the muxwait list are owned, 
then ERROR MUTEX _OWNED is returned. 

If any of the mutex semaphores in the muxwait list have dead own- 
ers (the process died without releasing the semaphore), then ER- 
ROR OWNER _DIED is returned. 

If the call returns because the time-out value was exceeded, then 
ERROR TIMEOUT is returned. 

Unless the calling process created the semaphore, it must first ob- 
tain access to it before issuing this call, otherwise ERROR_INVALID_ 
HANDLE is returned. 

If the call is interrupted due to an exception, or a no-wait I/O 
event occurred, then ERROR_INTERRUPT is returned. 


RESTRICTIONS/WARNINGS 


@ When blocking on muxwait semaphores in PM threads, WinWait- 
MuxWaitSem should be used instead of DosWaitMuxWaitSem to en- 
sure that the message queue for the thread can be serviced while 
blocked on a muxwait semaphore. 
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Semaphore Structures 





hsemCur (HSEM) 0 
The handle of an event or mutex semaphore. All semaphore records for a given muxwait 
semaphore must be of the same type (i.e. event or mutex). However, shared and private 
semaphores of the same type can be mixed. 


ulUser (ULONG) 4, 


This field is not used by the system, and can be set to any value the user desires. This value 
is returned to the caller on a DosWaitMuxWaitSem. 


Used by: DosAddMuxWaitSem -322, DosCreateMuxWaitSem -325, 
DosQueryMuxWaitSem -330 





Session 
Management 





ao can be thought of as a logical console, consisting of buffers 
or the screen, keyboard, and mouse. Sessions are the organiza- 
tional unit for user device I/O in OS/2. They ensure that input is di- 
rected to the correct process. The foreground session is the only one 
that can receive user device I/O. OS/2 allows an application to start 
another process of any type in a separate session by calling DosStart- 
Session. After creating the desired session type, DosStartSession starts 
the desired program using DosExecPgm (pg. 259). Programs of differ- 
ent types (such as PM, VDM) must be executed in separate sessions. 
Multiple processes of the same type can execute in the same session 
(see DosExecPgm, pg. 259). 

All Presentation Manager processes execute in the same session 
since there is currently only one logical console supported for 
Presentation Manager programs; however, DosStartSession will return 
a unique session ID for each PM process for the purpose of session 
management. 

Sessions may be started as child or unrelated sessions. Those 
started as child sessions are under the control of the parent session 
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and may be manipulated using the session management functions out- 
lined in this chapter. Unrelated sessions cannot be manipulated by us- 
ing the session management functions. It is important to understand 
that there is no parent-child process relationship established between 
parent and child sessions. Therefore, functions requiring a parent- 
child process relationship will not succeed. Sessions started by the op- 
erating system are always started unrelated. When a new session is 
started its title is placed in the Window List. If there is no title speci- 
fied, then the name of the executable is used. 

Child sessions can be stopped by the parent session at any time by 
calling DosStopSession; every descendant session beyond the child 
session will be terminated as well. Since child sessions can refuse to 
terminate (via exception handling), termination queues must be 
used to determine when a child session has terminated. Termination 
queues are OS/2 queues created by the parent session and passed to 
the DosStartSession call(see Chapter 12, Queues). The system will 
write the session ID and the reason for termination to the queue upon 
termination. 

Child sessions may be bound to their parents with DosSetSession. 
A child session that is bound to a parent session will be brought to the 
foreground whenever the parent is selected. Child sessions can also be 
set so that they cannot be selected via user input using DosSetSession. 
Nonselectable sessions cannot be switched to via system hotkeys, nor 
can they be selected from the task list; however, they are still selectable 
by calling DosSelectSession. DosSelectSession brings the specified 
child session to the foreground if the parent session or one of its chil- 
dren are in the foreground. 

Session Management functions are serviced by the shell, so there 
must be a shell running to use these functions. Additionally, only 
processes started by the shell can use the session management func- 
tions. The default shell for OS/2 is PMSHELL.EXE. The shell process 
is always assigned a session ID of 1, however, the shell cannot be ma- 
nipulated using the Session Management functions. 


Restrictions and Warnings 


@ There is a system limit of 255 sessions. 

e Although OS/2 allows different shells to be specified via the CON- 
FIG.SYS PROTSHELL statement, the APIs necessary to write a shell 
that support the session management functions are private. 
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@ Session Management functions cannot be used when: 


The calling process was started using the RUN (in CONFIG.SYS) or 
DETACH command. 

A VIO pop-up is up. 

You are running OS/2 without a shell process (such as Presentation 
Manager). 

The process calling the session manager function was not started by 
the shell. 


Only child sessions can be the targets of Session Management func- 
tions, and no session descending beyond the child session may be 
specified. 


Functions 





DosSelectSession switches to the specified child session (pg. 337). 
DosSetSession sets the selectability and bonding of a child session 
(pg. 338). 

DosStartSession starts an application in another session (pg. 340). 
DosStopSession ends one or all child sessions (pg. 344). 





@ DosSelectSession Session Management 


Allows a parent session to switch itself or a child session to the fore- 
ground. 

SYNTAX 

APIRET DosSelectSession(ULONG wilSessId) 


PARAMETERS 


ulSessId - input 
The ID of the session to be switched to the foreground. wlSessId must 
be the issuing session (specified by a zero) or a child session ID. 
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RETURNS 
0 NO_ERROR 459 ERROR SMG BAD RESERVE 
224 ERROR SMG NO_ 460 ERROR SMG PROCESS _ 
TARGET WINDOW NOT_PARENT 
369 ERROR SMG INVALID. 463 ERROR SMG RETRY_ 
SESSION_ID SUB_ALLOC 
418 ERROR SMG INVALID CALL 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSSESMGR 
Ordinal: 38 DLL: SESMGR 
SEE ALSO 


DosSetSession -338, DosStartSession -340, DosStopSession -344 


NOTES 


The foreground session for windowed applications is the session of the 
application that owns the window focus. 


RESTRICTIONS/WARNINGS 


@ Presentation Manager sessions can only be selected if they have a 
window with the FCF_TASKLIST bit specified. ERROR_SMG_NO_ 
TARGET _ WINDOW will be returned if there is no window with this 
bit specified. However, if a PM window is later created for that ses- 
sion with the FCF_TASKLIST flag, then the session will be brought 
to the foreground if the call is still in the foreground. 

@ This call only works if the parent session or one of its descendant ses- 
sions is currently executing in the foreground. 

@ DosSelectSession is blocked during VIO pop-ups. 





@ DosSetSession Session Management 


Sets the selectability and bonding of a child session. 


SYNTAX 
APIRET DosSetSession(ULONG ulSessID, PSTATUSDATA pStatusData) 
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PARAMETERS 


ulSessID - input 

The ID of a child session, which must be the ID returned from a 
DosStartSession call. 

pStatusData - input 

The address of a STATUSDATA structure (see pg. 346). 


RETURNS 
0 NO_ERROR 456 ERROR SMG _ INVALID _ 
SELECT _OPT 
369 ERROR SMG INVALID. 460 ERROR SMG PROCESS _ 
SESSION_ID NOT_PARENT 
418 ERROR SMG INVALID. 461 ERROR SMG INVALID _ 
CALL DATA LENGTH 
455 ERROR SMG _ INVALID. 463 ERROR SMG _RETRY_ 
BOND_OPTION SUB_ALLOC 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSSESMGR 
Ordinal: 39 DLL: SESMGR 
SEE ALSO 


DosSelectSession -337 


NOTES 


DosSetSession sets or resets one or both of the following parameters of 
a child session: 


@ Selectability: Determines whether the child session is selectable 
from the task list or via hotkey. (See the wsSelectInd parameter of the 
STATUSDATA structure on pg. 346) 

@ Bonding: Bonds a child session to its parent. This means that if the 
operator subsequently selects the parent session from the task list or 
via hotkey, the child session will be brought to the foreground. (See 
the usBondInd parameter of the STATUSDATA structure on pg. 
346.) 


These parameters do not affect selections made by the parent session 
via DosSelectSession. In other words, selections made programmati- 
cally are honored regardless of these settings. 
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If a bonding is established along a hierarchy of sessions, and a par- 
ent session within that hierarchy is selected by the user, the last session 
in the hierarchy is brought to the foreground. For example: 


A ->B->C 


A, B , and C are sessions, and the arrows indicate the direction of the 
hierarchy, with C being the lowest in the hierarchy. If the user selects 
session A or B, session C will be brought to the foreground. If session 
A selects itself (via DosSelectSession), then session A is brought to the 
foreground. However, if session A selects session B, the bond between 
B and C is honored, and session C is brought to the foreground. 


RESTRICTIONS/WARNINGS 


@ This function only works on child sessions. 





DosStartSession Session Management 





Starts a program in a new session. 


SYNTAX 


APIRET DosStartSession (PSTARTDATA pStaritData, PULONG 
pSessID, PPID ppidPID) 


PARAMETERS 

pStartData - input 

Address of the STARTDATA structure (pg. 347). 

pSessID- output 

The address of a ULONG to receive the session ID of the new child ses- 
sion. This value is only returned for child sessions. 

ppidPID- output 

The address of a PID to receive the process ID of the new process. This 
value is only returned for child sessions. The PID returned may not be 
used on any system functions that require a parent-child process rela- 
tionship. Read “Parent-Child Relationships” in the Notes section for 
more information. 


RETURNS 


0 NO_ERROR 457 ERROR_SMG_START_IN_ 
BACKGROUND 
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2 ERROR FILE NOT_ 460 ERROR SMG PROCESS _ 
FOUND NOT_PARENT 
3 ERROR _PATH_ NOT. 463 ERROR SMG RETRY_ 

FOUND SUB_ALLOC 

123 ERROR_INVALID _ 478 ERROR SMG _ INVALID _ 
NAME TRACE _ OPTION 

164 ERROR MAX THRDS 479 ERROR VIO_INTERNAL_ 
REACHED RESOURCE 

343 ERROR_QUE_NAME_ 491 ERROR SMG INVALID _ 
NOT_EXIST PROGRAM_TYPE 

369 ERROR SMG INVALID. 492 ERROR SMG INVALID _ 
SESSION_ID PGM_ CONTROL 

418 ERROR SMG INVALID. 493 ERROR SMG INVALID _ 
CALL INHERIT_OPT 

453 ERROR_SMG_ INVALID. 506 ERROR SMG INVALID _ 
START _MODE ICON_ FILE 

454 ERROR SMG _ INVALID RELATED OPT 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSSESMGR 

Ordinal: 37 DLL: SESMGR 

SEE ALSO 


DosExecPgm -259, DosStopSession -344, WinStartApp 


NOTES 


This call allows any protected-mode application to start any other pro- 
tected-mode application in a new session, regardless of the issuing pro- 
grams session type. 

If the length of [conFile is zero when starting a DOS session, ER- 
ROR_INVALID_ NAME is returned. 

If the length of the PomTiile is greater than 61 bytes, then the title 
is truncated to 61 bytes. 

If the program to start cannot be found, then ERROR_FILE_ 
NOT_FOUND is returned. 

If IconFile contains an invalid icon, then ERROR_SMG INVALID _ 
ICON_FILE is returned. 

If YermQ has not already been created, then ERROR_QUE_ 
NAME_NOT_EXIST is returned. 

Unlike WinStartApp, this call does not allow you to specify a 
startup directory. DosSetCurrentDir may be used to temporarily 
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change the directory to what you want for the new session before issu- 
ing this call. 

Foreground/Background Effects: For windowed applications, the 
session that has the focus is the session in the foreground. 

DosStartSession will only start sessions in the foreground if the 
program issuing DosStartSession or a descendant session is executing 
in the foreground session. Otherwise, DosStartSession will override 
the foreground request and start the new session in the background 
and return ERROR_SMG_START_IN_BACKGROUND. 

Parent-child Relationships: DosStartSession does not establish a 
parent-child process relationship regardless of whether the new session 
is a child. Therefore, the process ID that is returned cannot be used 
with any APIs that require a parent-child relationship. The parent 
process for processes started with DosStartSession is the shell process. 

Once a process creates a child session, no other process within the 
same session can create related sessions until all child sessions from 
the first process have terminated. 

Debuggers: For those writing debuggers, a special trace option 
(SSF_TRACEOPT_TRACEALL) is provided that allows all processes 
started from a child session to be debugged regardless of how they 
were started (for example, DosExecPgm and DosStartSession). When 
this option is specified, the caller must start the session as a child and 
provide the name of an existing queue. 

Whenever a new process is started from the child session or one of 
its descendant sessions, the session manager posts a data element to 
the queue that contains the session ID and process ID of the new ses- 
sion. The data element is posted regardless of whether the new session 
is a child. Any session started without the inheritance option is started 
in trace mode. It is the debugger’s responsibility to resume execution 
of the new process. 

The debugger must have a thread available to read the queue (see 
DosReadQueue, pg. 296) in blocking mode to receive notification that 
a new session is starting. The request parameter returned by Dos- 
ReadQueue will have a value of 1, and the data element returned has 
the following structure: 


Size Description 
WORD Session ID 
WORD Process ID 
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The debugger process is the only one with addressability to the 
data element, and should free the segment containing the element 
with DosFreeMem after it finishes processing it. 

The debugger may switch itself or a descendant session to the fore- 
ground using DosSelectSession whenever the current foreground ses- 
sion is a descendant of the debugger. 

PgmName and PgmInputs: ‘The program specified in PgmName is 
executed directly, with no intermediate secondary command proces- 
sor (such as CMD.EXE). If desired, a program can be executed 
through a secondary command processor by specifying CMD.EXE for 
PgmName, and by specifying either /C or /K followed by the fully qual- 
ified path of the application to be loaded for PgmInputs. This is useful 
for starting REXX and batch files. The /C switch causes the session to 
terminate when the program terminates, whereas the /K switch indi- 
cates that the session should remain until the EXIT command is en- 
tered after the process terminates. 

The Program Handle: Program handles are returned via the 16-bit 
APIs WinAddProgram and WinQueryProgramHandle. There are no 
32-bit equivalents to these APIs 

If a process issues DosStartSession specifying only the program 
handle, then it must change to the working directory before issuing 
DosStartSession, and start the new process as inherited. If a process is 
started as noninherited, it is up to that process to change to the correct 
directory. 

Parent-child Termination: The parent session becomes the fore- 
ground session when its child session ends. When a parent session 
ends, all its descendant sessions are ended. When an independent ses- 
sion ends in the foreground, the shell selects the next foreground 
session. 

Termination Queues: If a parent session wants to be notified when 
a child session terminates, it must create a termination queue, which is 
an OS/2 queue created for the purpose of termination notifications. 
Only an existing queue name can be passed to the DosStartSession 
function. 

When a child session terminates for any reason, the Session 
Manager writes a queue element to the queue that contains the session 
ID of the terminating session and its result code. A thread should be 
dedicated to block on a DosReadQueue to receive the notifications. 
The data element has the following structure: 
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Size Description 
WORD Session ID of child 
WORD Result code 


The value of the result code is the return code of the program 
when it returns from main{ } or the value specified for the ulReturnCode 
parameter of DosExit( ) provided that: 


@ the program is executed directly, with no intermediate command 
processor (such as CMD.EXE), or 

@ the program is executed indirectly through CMD.EXE with the /C 
parameter. 


Otherwise, the result code of the command processor is returned. 

The calling process is the only one with addressability to the ele- 
ment, and should free the element after processing with DosFreeMem. 

When the last child session has terminated, the Session Manager 
destroys the queue. A new termination queue must be created to re- 
ceive termination notifications for new child sessions. 

If desired, the termination queue may be used for additional in- 
terprocess communications with DosWriteQueue. Request parameters 
from 0 through 99 are reserved for the system. 

Starting Windows Programs: To start Windows programs, it is nec- 
essary to specify WINOS2.COM as the name of the program. The 
name of the program is then specified as if it were a parameter, and 
should be prefixed with either a /C or /K. The /K parameter indicates 
that the session should live after the program terminates. For example: 





StartData.PgmName = "“c:\os2\mdos\winos2\winos2.com”; 
StartData.PgmInputs = ”“/k c:\os2\mdos\winos2\clock.exe’”; 
DosStopSession Session Management 
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Stops child sessions. 


SYNTAX 
APIRET DosStopSession(ULONG wilTargetOption, ULONG wilSessID) 


PARAMETERS 
ulTargetOption - input 
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Specify whether the given child session or all child sessions are to be 
terminated. 


Constant = Description 

STOP_SESSION_SPECIFIED Q Ends only the child session specified 
in ulSessLD. 

STOP_SESSION_ALL 1 Ends all child sessions. 


ulSessID- input 

The ID of the child session to be terminated. No ID of a session de- 
scending beyond the child session can be specified. If ulTargetOption is 
set to 1, this value is ignored. 


RETURNS 
0 NO_ERROR 456 ERROR SMG INVALID _ 
SELECT_OPT 
369 ERROR SMG _ INVALID. 460 ERROR SMG PROCESS _ 
SESSION_ID NOT_PARENT 
418 ERROR SMG INVALID. 461 ERROR SMG INVALID _ 
CALL DATA LENGTH 
455 ERROR SMG INVALID. 463 ERROR SMG _ RETRY_ 
BOND_ OPTION SUB_ALLOC 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSSESMGR 
Ordinal: 14 DLL: SESMGR 
SEE ALSO 


DosStartSession -340 


NOTES 


If the target session has child sessions, those sessions will be terminated 
as well. Ifa child session is executing in the foreground at the time it is 
ended, the parent session becomes the foreground session. 

Since processes can refuse to be terminated via exception han- 
dling, the only way to guarantee that the target session has ended is to 
wait for notification through a termination queue specified in the 
DosStartSession call. 
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RESTRICTIONS/WARNINGS 


@ This function only works on child sessions. Sessions descending be- 
yond the child session cannot be the target of this function. 


Session Management Structures 





usLength (USHORT) 0 
The length of the data structure in bytes, including usLength itself. 
usSelectInd (USHORT) 2 
Sets the selectability of the session, as follows: 
Constant = Description 
SET_SESSION_UNCHANGED 0 Leave the current setting unchanged. 
SET_SESSION_SELECTABLE 1 Make the target session selectable. The 


session can be selected from the switch 
list or via system hotkey processing. This 
is the default upon creation of a new ses- 
sion. 


SET_SESSION_NON_SELECTABLE 2 Make the target session nonselectable. 
The session is not selectable from the 
shell switch list or via system hotkey. 
Windowed sessions can still be selected 
by pressing a mouse button on a visible 
region of the window. The session is also 
still selectable via DosSelectSession. 


usBondInd (USHORT) 4 
Specify the session to bring to the foreground the next time the parent session is selected, 
as follows: 
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Constant = Description 
SET_SESSION_UNCHANGED Q Leave the current setting unchanged. 
SET_SESSION_BOND 1 Bond the child session to the parent. 


The child session will be brought to the 
foreground when the parent is selected. 


SET_SESSION NO_BOND Z Break the bond between the child ses- 
sion and the parent. When the parent 
session is selected, it will be brought to 
the foreground. When the child session 
is selected, it will be brought to the fore- 
ground. This is the default for the cre- 
ation of new child sessions. 


Used by: DosSetSession (pg. 338) 





Length (USHORT) 0 
The length of this structure in bytes, including this field. This value can be 24, 30, 32, 50, or 
60 bytes depending on the type of session to start. When a length that is less than 60 is spec- 
ified, the remaining fields are filled in automatically by the shell. 

Only 32 bytes are required to start a DOS session by its session type. If Presentation 
Manager is not running, then the maximum length is 32 bytes. When the length is less than 
32 bytes, the shell will automatically determine the correct session type to start by calling 
DosQueryAppType on the executable. 

A length of at least 30 bytes is required to specify the environment and inheritance op- 
tions. A length of at least 50 bytes is required to specify windowing options, and a length of 
60 bytes is required to receive error information returned when the shell is unable to start 
the requested program. 


Related (USHORT) 2 


Parent-child session options: 
Constant = Description 


SSF_RELATED_INDEPENDENT Q Start the session as an independent ses- 
sion. Independent sessions cannot be 
controlled by their parents via the 
Session Manager functions. In addition, 
the TermQ field is ignored, and ulSessID, 
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and pidPID parameters are not re- 
turned. 


SSF_RELATED CHILD 1 Start the session as a child (related) ses- 
sion. 


Refer to “Parent-child Relationships” in the Notes section for additional information. 


FgBg (USHORT) 4 


Foreground/background options: 


Constant 2 Description 
SSF_FGBG_FORE Q Start the session in the foreground. 
SSF_FGBG_BACK 1 Start the session in the background. 


Refer to “Foreground/Background Effects” in the Notes section for additional information. 


TraceOpt (USHORT) 6 


Trace options: 


Constant = Description 
SSF_TRACEOPT_NONE Q0 No tracing. 
SSF_TRACEOPT_TRACE 1 Trace immediate child session and no 
descendants. 
SSF_TRACEOPT _TRACEALL 2 Trace all descendant sessions. Related 


must be 1, and a termination queue 
must be supplied when this option is 
used. Refer to “Debuggers” in the Notes 
section for additional information 
about a TraceOpt of 2. 


PgmTitle (PSZ) 8 
The address of a null-terminated string containing the program title. The title may be up to 
61 bytes long, including the null terminator. If PomTitle is NULL, or if the length of the 
PomTitle is zero, then the initial title is PgmName minus any leading drive and path informa- 
tion. This title will appear in the Window List. 


PgmName (PSZ) 12 
The address of a null-terminated string that contains the fully qualified path of the program 
to be executed. For REXX programs and BATCH files, specify CMD.EXE for this parame- 
ter, and a /C or /K followed by a space, and then the name of the REXX program or 
BATCH file for PgmInputs. For Windows programs, specify WINOS2.COM for this parame- 
ter, and a /C or /K followed by a space, and then the name of the Windows program for 
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PemInputs. Refer to “Starting Windows Programs” in the Notes section for additional infor- 
mation. 

If PomName is NULL, or the length of PgmName is zero, then PgmHandle is checked. If 
PgmHandle is not zero, then the program PgmHandle references is started. If PgmHandle is 
zero and the session type is a DOS session, then the command processor specified by the 
SHELL statement in CONFIG.SYS is executed. If PgmHandle is zero and the session type is 
an OS/2 session, then the command processor specified by the OS2_SHELL statement in 
CONFIG.SYS is executed. The combined length of PemName and PgmInputs may not exceed 
1024 characters. 


PgmInputs (PBYTE) 16 
Either a NULL for no arguments, or the address of a null-terminated string containing the 
arguments to be passed to the program. These arguments must be delimited by nulls and 
end with a double null. By convention, the first parameter passed to a program is the name 
of the program itself. 


TermQ (PBYTE) 20 
Either NULL, or the address of a null-terminated string that contains the fully qualified 
path and file name of a previously created OS/2 queue (see DosCreateQueue, pg. 291). 
Refer to “Iermination Queues” and “Debuggers” in the Notes section for additional infor- 
mation about the TermQ field. 


Environment (PBYTE) 24 
Either NULL, or the address of a null-terminated environment string to be passed to the 
program started in the new session. Environment settings are null-delimited, with the final 
setting being double null-terminated. For example: 


Environment = “SET TEMP=D:\TMP\OSET BOOK=D: \BOOK;C:\BOOK\0”; 


If the Environment field equals zero and the Jnhent Opt field is set to SSF_INHERTOPT_ 
SHELL, then the shell environment is used. If the Environment field equals zero and the 
InhenitOpt field is set to SSF_INHERTOPT_PARENT then the calling process environment is 
used. 

The DOS settings found in the settings notebook for DOS sessions can be used in the 
Environment parameter; however, normal DOS environment strings cannot be used in the 
Environment parameter. DOS environment strings must be placed in an AUTOEXEC.BAT 
file, or placed in a DOS batch file that will set the environment and then start the program. 
The location of the AUTOEXEC.BAT file may be specified as one of the environment set- 
tings (refer to the settings notebook). The following undocumented method may be used 
to set DOS environment settings: 

The settings that equate to on or off should be set to either 1 or 0 respectively. For ex- 
ample: 


“DOS_DDE=1\0DOS_AUTOEXEC=D: \AUTO2 .BAT\O0DOS_FCBS=16\0" // DDE = On 


Strings are set normally. 
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Refer to the settings notebook of a DOS program object for available DOS settings. 
The maximum environment size supported in OS/2 is 64k. 


InheritOpt (USHORT) 28 
Specify whether the program should inherit the calling program’s environment and open 
file handles as follows: 


Constant = Description 
SSF_INHERTOPT_SHELL 0 Inherit the environment of the shell. 
SSF_INHERTOPT_PARENT 1 Inherit the environment of the calling 

program. 


The new program will not inherit the calling program’s priority regardless of which op- 
tion is chosen. New programs are started with Regular priority class, and a zero priority 
level. 

Refer to “Parent-child Relationships” in the Notes section for additional information 
about related sessions. 


For DOS sessions: 
An InhentOpt value of 1 for a DOS session only inherits the parent’s current drive and path, 
and no Environment. 


SessionType (USHORT) 30 


Specify one of the following session types: 
Constant = Description 


SSF_TYPE_ DEFAULT 0 Use the PgmHandle to determine the ses- 
sion type. If no PgmHandle was specified, 
the shell will determine the session type. 


SSF_TYPE_FULLSCREEN 1 Start the program in a full-screen ses- 
sion. 


SSF_TYPE_WINDOWABLEVIO 2 Start the program in a windowed session 
for OS/2 programs using the Base 
Video Subsystem. 


SSF_TYPE_PM 3 Start the program in a windowed session 
for programs using Presentation Man- 
ager (including AVIO calls). 


SSF TYPE VDM 4 Start the program in a full-screen DOS 
session. 
SSF_TYPE_WINDOWEDVDM 7 Start the program in a windowed DOS 


session. 
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Windows: See the notes in the PgmName structure member for more information on start- 
ing Windows programs. 


IconFile (PSZ) 32 
Either NULL, or a null-terminated string containing the fully qualified file name of an icon 
file. If NULL is specified, the system will look for a .ICO file with the same prefix in the same 
directory of the program to be started and in the .[CON extended attribute of the exe- 
cutable (see WinLoadFileIcon for more information on how the system finds icons). 


PgmHandle (ULONG) 36 
Either NULL, or a program handle returned by one of the following 16-bit PM APIs: 
WinAddProgram, and WinQueryProgramHandle. The program handle references the pro- 
gram to be started, its title, session type, and initial window size and position. These values 
can be overridden by specifying them in this structure. 

The PgmHandle from a WinCreateGroup call may not be used as input for DosStartSession. 


PgmControl (USHORT) 
This field can be used to specify windowing options for windowed applications. It is ignored 
for full-screen sessions. Windowed applications that explicitly define their window states 
may not be affected by these settings. 

Bitwise OR the following values to achieve the desired initial window state: 


Constant = Description 
SSF_CONTROL_VISIBLE 0x0000 Visible 
SSF_CONTROL_INVISIBLE 0x0001 Invisible 
SSF_CONTROL_MAXIMIZE 0x0002 Maximize 
SSF_CONTROL_MINIMIZE 0x0004 Minimize 


SSF_CONTROL_NOAUTOCLOSE 0x0008 No Auto Close 
SSF_CONTROL_SETPOS 0x8000 Use specified size and position 


Note: The SSF_CONTROL_NOAUTOCLOSE bit only applied to VIO Window-able appli- 
cations. 


InitXPos and InitYPos (USHORT) 40, 42 
Specify the initial x and y coordinates, in pels (pixels), to display the initial window, with the 
left corner of the screen being the origin (0,0). The SSF_CONTROL_SETPOS flag must be 
specified for PgmControl to use this feature. This field is only valid for windowed sessions. 


InitXSize and InitYSize (USHORT) 44, 46 
Specify the initial x and y size, in pels (pixels), for the initial window. The SSF_CON- 
TROL_SETPOS flag must be specified for PgmControl to use this feature. This field is only 
valid for windowed sessions. 
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Reserved (USHORT) 48 
Set this field to zero—it is reserved for future use. 
ObjectBuffer (PSZ) 52 


The address of a buffer that will receive the name of the object (usually a DLL) that caused 
the application to fail to start. This field is the same as the pOlbjNameBuf field in DosExecPgm 
(see pg. 259). DosStartSession uses DosExecPgm to start full-screen, VIO windowed, and 
Presentation Manager programs. 


ObjectBuffLen (ULONG) 56 
The length of the ObjectBuffer in bytes. 


Used by: DosStartSession (pg. 340) 


IMMers 








S/2 provides three types of timers that can be used to suspend ex- 

ecution of a thread: asynchronous single-interval, asynchronous 
multiple-interval, and synchronous. All supported timers run off of the 
system clock, which means they are limited to an accuracy of the dura- 
tion of one clock tick. On most machines, clock ticks typically occur 
about 32 times a second with a duration of about 31.25 milliseconds 
(tick duration = 1 sec./32). Therefore, if an application requests a 
timer interval of 5 milliseconds, it will be rounded up to 31.25 mil- 
liseconds (or one clock tick). DosQuerySysInfo (pg. 109) can be used 
to determine the timer interval on a particular machine. 

In addition to the timer interval, the fact that OS/2 is a preemp- 
tive operating system must be taken into consideration when deter- 
mining accuracy. Just because the desired interval has expired does 
not mean that the thread will begin executing immediately. This will 
depend on the priority of the thread and whether other threads of 
higher priority are ready to run. 


Asynchronous Single-interval 
DosAsynchTimer may be used to start an asynchronous timer that will 


signal only once. It takes an event semaphore handle as a parameter and 
the length of the timer interval in milliseconds. When the interval has 
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expired, the semaphore is posted. The semaphore must be a named or 
unnamed shared semaphore, and the calling process must have access to 
the semaphore before calling DosAsynchTimer. 


Asynchronous Multiple-interval 


DosStartTimer may be used to start an asynchronous timer that will re- 
peatedly signal at the specified interval indefinitely until DosStop- 
Timer is called. DosStartTimer takes an event semaphore handle as a 
parameter and the length of the timer interval in milliseconds. Each 
time the interval expires, the semaphore is posted. The semaphore 
must be a named or unnamed shared semaphore, and the calling 
process must have access to the semaphore before calling DosAsynch- 
Timer. DosResetEventSem will return the post count of the semaphore 
and reset the post count of the semaphore to zero. The post count of 
the semaphore can be used to determine if the application missed an 
interval. 


Synchronous Timers 


DosSleep may be used as a synchronous timer. It takes one parame- 
ter—the interval in milliseconds—and blocks execution of the calling 
thread until the interval expires. It is important to note that, unlike the 
asynchronous timers, this interval is based on CPU time and not real 
time. Therefore, the accuracy provided with DosSleep will be far less 
than the asynchronous timers. A value of zero may be passed to 
DosSleep to cause the calling thread to give up the remainder of its 
timeslice. If there are no other higher priority threads ready to run on 
the system at the time of the call, it will return immediately. In other 
words, no yield will occur if the calling thread is the highest priority 
thread ready to run at the time of the call. 


Date and Time 


The system provides two functions for getting and setting the date 
and time maintained by the operating system. DosGetDateTime and 
DosSetDateTime can be used to query and set the current date and time 
respectively. 
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Warnings and Restrictions 


@ The Control Program timer functions should not be used on 
threads running a Presentation Manager queue. WinStartIimer 
should be used instead. 

@ DosSleep should not be used when the greatest accuracy is desired, 
since DosSleep will be subject to the total number of scheduled ac- 
cumulated timeslices (or CPU time) instead of elapsed real time. 

@ The system supports a maximum of 255 simultaneous asynchronous 
timers. 


Timer Functions 





DosAsynchTimer starts an asynchronous, single interval timer (pg. 
355). 

DosSleep suspends the calling thread for the duration of the specified 
interval (pg. 356). 

DosStartTimer starts an asynchronous, multiple interval timer (pg. 
357). 

DosStopTimer stops asynchronous, single and multiple interval timers 


(pg. 358). 





@ DosAsynchTimer Timers 


Starts an asynchronous, single-interval timer. 


SYNTAX 


APIRET DosAsynchTimer(ULONG wlTimerInterval, HSEM 
hsemEventSem, PHTIMER phtTimer) 


PARAMETERS 


ulTimerInterval - input 
The duration, in milliseconds, before hsemEventSem is posted. 


356 


os/2® Warp Control Program API 


hsemEventSem - input 

The handle of a shared event semaphore to post when the interval has 
expired. The semaphore should be reset before making this call. 
phtTimer - output 

The address of an HTIMER that will receive the timer handle. This 
handle can be used to stop the timer before its interval expires by call- 
ing DosStopTimer. 


RETURNS 
0 NO_ERROR 324 ERROR TS NOTIMER 
323 ERROR _ TS SEMHANDLE 
OTHER INFO 
Include file: bsedos.h Define: INCL_DOSDATETIME 
Ordinal: 350 DLL: DOSCALLS 
SEE ALSO 


DosCreateEventSem -307, DosOpenEventSem -308, 
DosResetEventSem-311, DosSleep -356, DosStartTimer -357, 
DosStopTimer -358, DosWaitEventSem -312 


NOTES 


Multiple timers can be assigned the same semaphore. 
ERROR_TS_NOTIMER is returned when there are no system 
timers available. 
ERROR TS SEMHANDLE is returned when an invalid sema- 
phore handle is specified, the semaphore handle is not a shared sema- 
phore, or the calling process does not have access to the semaphore. 





DosSleep Timers 


Blocks the calling thread for the specified time interval. 


SYNTAX 
APIRET DosSleep(ULONG ullnierval) 


PARAMETERS 


ullnterval - input 
The duration, in milliseconds, to suspend execution of the calling 
thread. 
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RETURNS 

0 NO_ERROR 322 ERROR TS WAKEUP 

OTHER INFO 

Include file: bsedos.h Define: INCL. DOSDATETIME 
Ordinal: 229 DLL: DOSCALLS 

SEE ALSO 


DosAsyncTimer -355, DosStartTimer -357, DosStopTimer -358, 
WinStart Timer 


NOTES 


This call will block the calling thread for the specified duration. If an 
interval of 0 is specified, then the calling thread gives up the remain- 
der of its timeslice. If there are no other higher priority threads in the 
system ready to run at the time of the call, it will return immediately. In 
other words, no yield will occur if the calling thread is the highest pri- 
ority thread ready to run at the time of the call. 

If DosSleep returns before the timer interval expires, ERROR_ 
TS _WAKEUP is returned. 


RESTRICTIONS/WARNINGS 


@ Unlike the asynchronous timers, DosSleep does not provide real- 
time timing. DosSleep will suspend execution of the calling thread 
for the accumulated CPU time. Therefore, the scheduling of the sys- 
tem plays a bigger role in the accuracy of DosSleep as a timer. For 
the greatest level of accuracy, use the asynchronous timers instead. 
Do not use DosSleep on threads running Presentation Manager 
message queues. The message queue cannot be serviced while the 
thread is blocked on DosSleep. Instead, use WinStartTimer for 
threads running Presentation Manager message queues. 





DosStartTimer Timers 





Starts an asynchronous, repeated interval timer. 


SYNTAX 


APIRET DosStartTimer(ULONG wlTimerInterval, HSEM 
hsemEventSem, PHTIMER phtTimer) 
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PARAMETERS 


ulTimerInterval - input 

The duration, in milliseconds, before hsemEventSem is posted. 
hsemEventSem - input 

The handle of a shared event semaphore to post each time the interval 
has elapsed. ‘The semaphore should be reset before making this call. 
phtTimer - output 

The address of an HTIMER that will receive the timer handle. This 
handle can be used to stop the timer at any time by calling DosStop- 
Timer. 


RETURNS 


0 NO_ERROR 324 ERROR_TS_NOTIMER 
323 ERROR_TS_SEMHANDLE 


OTHER INFO 


Include file: bsedos.h Define: ,INCL_DOSDATETIME 
Ordinal: 351 DLL: DOSCALLS 


SEE ALSO 


DosAsyncTimer -355, DosCreateEventSem -307, 
DosOpenEventSem -308, DosResetEventSem -311, DosSleep -356, 
DosStopTimer -358, DosWaitEventSem -312 


NOTES 


Multiple timers can be assigned the same semaphore. 
ERROR_TS_NOTIMER is returned when there are no system 
timers available. 
ERROR _ TS SEMHANDLE is returned when an invalid sema- 
phore handle is specified, the semaphore handle is not a shared sema- 
phore, or the calling process does not have access to the semaphore. 





DosStop Timer Timers 


Stops a single or multiple-interval asynchronous timer. 


SYNTAX 
APIRET DosStopTimer(HTIMER htTimer) 
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PARAMETERS 
htTimer - input 
The handle of the asynchronous timer to stop. 


RETURNS 

0 NO_ERROR 326 ERROR_TS_HANDLE 

OTHER INFO 

Include file: bsedos.h Define: ,INCL_DOSDATETIME 
Ordinal: 290 DLL: DOSCALLS 

SEE ALSO 

DosAsyncTimer -355, DosSleep -356, DosStartTimer -357 

NOTES 

DosStopTimer may be used to stop single-interval or multiple-interval 
timers. 


ERROR _TS_ HANDLE is returned when a bad timer handle is 
specified, or the timer handle references a timer that has already ter- 
minated. 


Date and Time Functions 





DosGetDateTime gets the current date and time (pg. 359). 
DosSetDateTime sets the current date and time (pg. 360). 





@ DosGetDateTime Date and Time 


Gets the current date and time maintained by the operating system. 


SYNTAX 
APIRET DosGetDateTime (PDATETIME pdtDateTime) 


PARAMETERS 


pdtDateTime - output 
The address of a DATETIME structure. 
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RETURNS 
0 NO_ERROR 


OTHER INFO 


Include file: bsedos.h Define: INCL _DOSDATETIME 
Ordinal: 230 DLL: DOSCALLS 


SEE ALSO 


DosAsyncTimer -355, DosSetDateTime -360, DosSleep -356, 
DosStartTimer -357, time 


NOTES 
The system obtains the date and time from CMOS at boot time. 





DosSetDateTime Date and Time 


Sets the date and time maintained by the operating system. 


SYNTAX 
APIRET DosSetDateTime (PDATETIME pdiDaieTime) 


PARAMETERS 


pdtDateTime - output 
The address of a DATETIME structure. 


RETURNS 

0 NO_ERROR 327 ERROR_TS_ DATETIME 
OTHER INFO 

Include file: bsedos.h Define: INCL_DOSDATETIME 
Ordinal: 230 DLL: DOSCALLS 

SEE ALSO 


DosAsyncTimer -355, DosGetDateTime -359, DosSleep -356, 
DosStartTimer -357, time 


NOTES 


The system will set the new date and time in CMOS so that the change 
is persistent across boots. 
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The system will verify that the values are within the correct ranges, 
and that the day is possible for the given month and year (including 
leap year). If any invalid values are specified in the DATETIME struc- 
ture, ERROR_TS_ DATETIME is returned. 


Date and Time Structures 





hours (UCHAR) 0 
The current hour. Valid values are 0 through 23. 

minutes (UCHAR) 1 
The current minute. Valid values are 0 through 59. 

seconds (UCHAR) 2 
The current second. Valid values are 0 through 59. 

hundredths (UCHAR) 3 
The current hundredths of a second. Valid values are 0 through 99. 

day (UCHAR) 4 
The current day. Valid values are 1 through 31. 

month (UCHAR) 5 
The current month. Valid values are 1 through 12. 

year (USHORT) 6 
The current year. Valid values are 1980 through 2079. 

timezone (SHORT) 8 


The difference in minutes between the systems time zone and Greenwich Mean Time 
(GMT). A positive value indicates a time zone west of Greenwich England, and a negative 
value indicates a time zone east of Greenwich. A value of -1 indicates the time zone is unde- 
fined. 


weekday (CHAR) 10 
The current day of the week. Valid values are 0 through 6. 
Used by: DosGetDateTime -359, DosSetDateTime -360 
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S/2 provides two address conversion routines to help program- 

mers who are in the process of converting their systems from 16- 
to 32-bit. These routines allow a program to convert a 16-bit selector 
and offset to a 32-bit flat virtual address and vice versa. Any memory al- 
located within the tiled compatibility region (the first 512Meg) can be 
converted. Currently, all memory allocable by applications is tiled, 
and therefore, convertible. DosFlatToSel is used to convert 32-bit flat 
addresses to 16-bit selector and offset, and DosSelToFlat is used to 
convert a 16-bit selector and offset to a 32-bit flat address. In some 
cases the use of these routines can be avoided when using compilers 
(like IBM CSet++) that support special keywords which will automati- 
cally perform the address conversion for you. Check your compiler 
documentation for more information. 

Two new, long-awaited routines are now available with OS/2 Warp 
for dynamic LIBPATH manipulation. DosSetExtLIBPATH and Dos- 
QueryExtLIBPATH allow programmers to dynamically set and query 
the “extended” LIBPATHs for their applications. Extended LIBPATHs 
are paths that are searched either before or after the normal LIB- 
PATH. Extended LIBPATHs only affect the process that defines them, 
and any child processes created thereafter by that process. Existing 
child processes are not affected by changes made by their parents. 
WARNING: OS/2 will only search the LIBPATH for a DLL that has not 
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already been loaded. The side effect of this is shown by the following 
example: An application named A loads a DLL, called X.DLL, from 
path C:\PATH] (a path found in the LIBPATH statement in the CON- 
FIG.SYS). Application B, running as a separate process, calls DosSet- 
ExtLIBPATH to change the beginning of the LIBPATH so that the sys- 
tem will first search path C:\PATH2, because it wants a special version 
of X.DLL to be loaded. Since there already is an X.DLL loaded, the sys- 
tem will reference the same DLL for application B as well. 

To avoid this side effect, an application must specify a full path for 
the DLL when it calls DosLoadModule. 


Address Conversion Functions 





DosFlatToSel converts a 0:32 bit address to a 16:16 bit address (pg. 363). 
DosSelToFlat converts a 16:16 bit address to a 0:32 bit address (pg. 364). 





@ DosFlatToSel Miscellaneous 





Converts a 32-bit flat virtual address (0:32) to a 16-bit selector and off- 
set (16:00). 


SYNTAX 
ULONG DosFlatToSel(PVOID pFlatAddress) 


PARAMETERS 


pFlatAddress - Input 
The 32-bit flat virtual address to be converted. 


RETURNS 
A selector and offset with the form 16:16. 


OTHER INFO 


Include file: Not prototyped Define: Not prototyped 
Ordinal: 425 DLL: DOSCALLS 
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SEE ALSO 
DosSelToFlat -364 


NOTES 


Your tool kit may not have the prototype for this function. 





@ DosSelToFlat Miscellaneous 





Converts a 16-bit selector and offset (16:16) to a 32-bit flat virtual ad- 
dress (0:32). 


SYNTAX 
PVOID DosSelToFlat(ULONG uwlSelector) 


PARAMETERS 


ulSelector - input 
The 16-bit selector and offset to be converted. 


RETURNS 
A 32-bit flat virtual address. 


OTHER INFO 


Include file: Not prototyped Define: Not prototyped 
Ordinal: 426 DLL: DOSCALLS 


SEE ALSO 
DosFlatToSel -363 


NOTES 


Your tool kit may not have this function prototyped. 


Extended LIBPATH Functions 





DosQueryExtLIBPATH obtains the path that will be searched for DLLs 
before or after the LIBPATH specified in the CONFIG.SYS (pg. 364). 
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DosSetExtLIBPATH sets the path to search for DLLs before or after 
the LIBPATH specified in the CONFIG.SYS (pg. 366). 





DosQueryExtLIBPATH Miscellaneous 


Queries the extended LIBPATH of the calling process. 


SYNTAX 
APIRET DosQueryExtLIBPATH (PSZ pszExtLIBPATH, ULONG /iFlags) 


PARAMETERS 


pszExtLIBPATH - output 

On input, the address of a buffer large enough to hold the requested 
extended LIBPATH. The maximum length of an extended LIBPATH 
is 1024 bytes. On output, the null terminated extended LIBPATH 
string of the calling process. If the extended LIBPATH is not defined, 
a NULL is returned in the buffer. 

fiflags - input 

The flag indicating which end of the extended LIBPATH to return. 


Constant Description 

BEGIN_LIBPATH 1 The path searched before the regular 
LIBPATH. 

End_LIBPATH 2 The path searched after the regular 
LIBPATH. 

RETURNS 

QO NO_ERROR 87 ERROR_INVALID_PARAMETER 

OTHER INFO 

Include file: bsedos.h Define: INCL _DOSMISC 

Ordinal: 874 DLL: DOSCALLS 

SEE ALSO 


DosLoadModule -12, DosSetExtLIBPATH -366 
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NOTES 


This routine only returns extended LIBPATH information. Appli- 
cations must search the CONFIG.SYS to determine the normal LIB- 
PATH. 





DosSetExtLIBPATH Miscellaneous 





Sets the extended LIBPATH of the calling process. 


SYNTAX 
APIRET DosSetExtLIBPATH (PSZ pszExtLIBPATH, ULONG /flFlags) 


PARAMETERS 


pszExtLIBPATH - output 

The address of a null-terminated buffer containing the extended LIB- 
PATH to set. Passing a null deletes the existing extended LIBPATH. 
The maximum length of an extended LIBPATH is 1024 bytes. 

fiflags - input 

The flag indicating which end of the extended LIBPATH to set. 


Constant Description 

BEGIN_LIBPATH 1 The path to search before the regular 
LIBPATH 

END_LIBPATH 2 The path to search after the regular 
LIBPATH. 

RETURNS 

0 NO_ERROR 87 ERROR_INVALID_PARAMETER 

8 ERROR _NOT_ 161 ERROR_BAD_PATHNAME 

ENOUGH_MEMORY 

OTHER INFO 

Include file: bsedos.h Define: INCL_DOSMISC 

Ordinal: 873 DLL: DOSCALLS 

SEE ALSO 


DosLoadModule -12, DosQueryExtLIBPATH -365 
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NOTES 


Setting a beginning or ending extended LIBPATH causes the existing 
one (if defined) to be replaced. An existing extended LIBPATH can be 
preserved by inserting %BeginLIBPATH% or %EndLIBPATH% in 
your new path string where desired. For example, if you wanted to 
change the ending extended LIBPATH while preserving the existing 
one, you would do the following: DosSetExtLIBPATH (“C:’\MyPath; %- 
EndLIBPATH%;F\\AnyPath”,End_LIBPATH); If the existing ending 
extended LIBPATH were set to C:\OrigPath, the resulting one would 
be: C:\MyPath;CAOrigPath;F:AnyPath 

Any child processes created after setting an extended LIBPATH 
will inherit the extended LIBPATHs. Changes made to the extended 
LIBPATH after the child process is created will have no effect on the 
child. 

Initial settings for extended LIBPATHs can be defined for all 
processes by setting the BeginLIBPATH and EndLIBPATH strings in 
the CONFIG.SYS. 


WARNINGS/RESTRICTIONS 


@ Extended LIBPATHs are only searched when the desired DLL is not 
already loaded. Therefore, another process may have already 
loaded a DLL with the same name as the one your application 
needs, and the DLL already loaded will be linked to your process re- 
gardless of your extended LIBPATH settings. To avoid this problem, 
an application must specify a fully-qualified path of the DLL they 
want when calling DosLoadModule. See page 362 of this chapter for 
a more detailed explanation. 





@ DosCancelLockRequest File Management 


Cancels an outstanding file locks request. 


SYNTAX 

APIRET DosCancelLockRequest(HFILE h/File, PFILELOCK 
pflLockRange) 

PARAMETERS 

hfFile- input 

The handle of the file which has the lock request to be canceled. 

pflLockRange- input 


The address of a FILELOCK structure containing the region of the 
lock that should be canceled. 


RETURNS 
0 NO_ERROR 87 ERROR_INVALID_PARA- 
METER 
6 ERROR_INVALID HANDLE 95 ERROR_INTERRUPT 
33 ERROR_LOCK_VIOLATION 174 ERROR_ATOMIC_LOCK 
_NOT_SUPPORTED 
36 ERROR_SHARING_BUFFER 175 ERROR _READ_ LOCKS 


_EXCEEDED _NOT_SUPPORTED 
OTHER INFO 
Include file: bsedos.h Define: INCL _DOSFILEMGR 
Ordinal: 429 DLL: DOSCALLS 
SEE ALSO 


DosSetFileLocks -43 
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WARNINGS/RESTRICTIONS 


@ This call is only effective in cancelling outstanding lock requests. In 
other words, the thread has requested a lock on a range, but is still 
waiting for that lock. 

@ The call cancels all lock requests for the given range for all threads 
of the calling process. 

@ Some file-system drivers do not support the cancellation of lock re- 
quests. LAN servers cannot cancel lock requests if they are running 
a version of OS/2 prior to version 2.0. 
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DosError, 30 

DosExecPgm, 256, 259-63 
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DosSendSignalException, 33, 36, 43 
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DosSetMaxFH, 59, 98-99 
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DosSetPathInfo, 62, 87 
DosSetPriority, 280-83 
DosSetProcessCp, 206-7 
DosSetRelMaxFH, 59, 99 
DosSetSession, 338—40 
DosSetSignalExceptionFocus, 33, 44~45 
DosSetSignalFocus, 33 
DosSetVerify, 89 

DosShutdown, 155-56 

DosSleep, 355, 356 
DosStartSession, 335, 336, 340—44 
DosStartTimer, 354, 357-58 
DosStopSession, 336, 344 
DosStopTimer, 354, 358-59 
DosSubAllocMem, 161, 180-82 
DosSubFreeMem, 182-83 
DosSubSetMem, 161, 183-85 
DosSubUnsetMem, 185-86 
DosSuspendThread, 275-76 
DosTransactNPipe, 251-52 
DosUnsetExceptionHandler, 39-40 
DosUnwindException, 35, 40-41 
DosWaitChild, 269 
DosWaitEventSem, 287, 303, 312-13 
DosWaitMuxWaitSem, 304, 331 
DosWaitNPipe, 217, 253-54 
DosWaitThread, 276 

DosWrite, 90, 227-29 
DosWriteQueue, 290 

dynamic link libraries (DDLs), see DLLs 
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EAAT_EA, 140 

EAOP2 structure, 132 

EAT ASCII, 139 

EAT _ASNI, 140 

EAT_BINARY, 139 

EAT_BITMAP, 139 

EAT_ICON, 140 

EAT_METAFILE, 139 

EAT MVMT, 140 

elements, queue, 286 

environment and path functions: 
DosScanEnv, 127-28 
DosSearchPath, 129-31 
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error handling, 27-30 
event semaphore functions, 305-13 
DosCloseEventSem, 306—7 
DosCreateEventSem, 307 
DosOpenEventSem, 308-9 
DosPostEventSem, 309-10 
DosQueryEventSem, 310 
DosResetEventSem, 311 
DosWaitEventSem, 312-13 
event semaphores, 302-3 
exception codes, format of, 52 
exception handling functions, 31-32, 36-41 
prototype of, 51-52 
values that may be returned by, 52 
exception handling structures, 48-51 
exceptions, 31-57 
exiting and, 35-36 
fatal hardware, 55-57 
fatal software-generated, 53-55 
nested, 35 
nonfatal software-generated, 53 
raising, 34 
signal, 33-34 
synchronous and asynchronous, 32 
system defined, 52-57 
unwinding, 35 
user-defined, 34 
extended attribute data types, 139-40 
extended attributes (EAs), 62-63 
standard (SEAs), 140 
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FAT file system, 142-44 
FDATE structure, 132 
FEA2 structure, 132-33 
FEA2LIST structure, 133 
FILEFINDBUFS3 structure, 133-34 
FILEFINDBUF4 structure, 134-36 
file handles, 58—59 
protected, 59 
FILELOCK structure, 136 
file management functions, 58-140 
directory and disk functions, 121-27 
DosCreateDir, 121-22 
DosDeleteDir, 123 
DosQueryCurrentDir, 124-25 
DosQueryCurrentDisk, 125-26 
DosSetCurrentDir, 126 
DosSetDefaultDisk, 1277 
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directory search functions, 113-21 
DosFindClose, 113 
DosFindFirst, 113-19 
DosFindNext, 119-21 
environment and path functions, 127-31 
file handle functions, 91-100 
DosDupHandle, 91-93 
DosQueryFHState/DosProtectQueryFHState, 
93-95 
DosQueryHType, 95 
DosSetFHState /DosProtectSetFHState, 97-98 
DosSetMaxFH, 98-99 
DosSetRelMaxFH, 99 
file manipulation functions, 63-91 
DosClose/DosProtectClose, 64 
DosCopy, 65 
DosDelete, 67-68 
DosEditName, 68—70 
DosForceDelete, 70-71 
DosMove, 71-73 
DosOpen/DosProtectOpen, 73-79 
DosRead/DosProtectRead, 779-80 
DosSetFileInfo/DosProtectSetFileInfo, 80 
DosSetFileLocks/DosProtectSetFileLocks, 
82-84 
DosSetFilePtr/DosProtectSetFilePtr, 84 
DosSetFileSize /DosProtectSetFileSize, 86—87 
DosSetPathInfo, 87 
DosWrite/DosProtectWrite, 90 
file query functions, 100-112 
DosEnumAttribute/DosProtectEnum, 101-3 
DosQueryFileInfo/DosProtectQueryFileInfo, 
103-6 
DosQueryPathInfo, 106-9 
DosQuerySysInfo, 109-12 
DosQueryVerify, 112 


file management structures, 131-39 


DENA2, 131 

EAOP2, 132 

FDATE, 132 

FEA2, 132-33 
FEA2LIST, 133 
FILEFINDBUF3, 133-34 
FILEFINDBUF4, 134-36 
FILELOCK, 136 
FILESTATUS3, 136-37 
FILESTATUS4, 137-38 
FTIME, 138 

GEA2, 138-39 
GEA2LIST, 139 


file names: 
command processor and, 61 
metacharacters in, 60-61 
file pointers, 60 
file region locking, 60 
FILESTATUS3 structure, 136-37 
FILESTATUS4 structure, 137-38 
file system, 141-58 
FAT, 142-44 
functions, 145-56 
DosFSAttach, 145-47 
DosFSCtl, 147-50 
DosQueryFSAttach, 150-52 
DosQueryFSInfo, 152-53 
DosResetBuffer, 153-54 
DosSetFSInfo, 154-55 
DosShutdown, 155-56 
local and remote, 144-45 
routine requests, 144 
structures, 157-58 
flat addressing, 159 
FSALLOCATE structure, 157 
FSQBUFFER structure, 157-58 
FTIME structure, 138 
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GEA2LIST structure, 139 
GEA2 structure, 138-39 
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high performance file system (HPFS), 143-44 
HPFS (high performance file system), 143-44 


I 
I/O control interface, 1-2 


K 
KEYBOARD.DCP, 204 


M 


memory 
shared, 160-61 
thread-local, 161-62 

memory commitment, 160 

memory functions, 162 
DosAllocMem, 162-65 
DosFreeMem, 165-66 
DosQueryMem, 169-71 
DosSetMem, 166-69 
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shared, 172-80 
DosAllocSharedMem, 172 
DosGetNamedSharedMem, 1'75—77 
DosGetSharedMem, 1'77~78 
DosGiveSharedMem, 178-80 
suballocation (heap management): 
functions, 180-86 
DosSubAllocMem, 180-82 
DosSubFreeMem, 182-83 
DosSubSetMem, 183-85 
DosSubUnsetMem, 185-86 
thread-local, 186 
DosAllocThreadLocalMemory, 186-87 
DosFreeThreadLocalMemory, 187 
memory management, 159-87 
memory objects, 160 
memory pools, 161 
memory suballocation (heap management): 
functions, 180 
message files, 188 
message management functions, 188-200 
DosGetMessage, 190 
DosInsertMessage, 193-95 
DosPutMessage, 195-96 
DosQueryMessageCP, 196-200 
loading and displaying messages, 189 
metacharacters, 60-61 
DosEditName and, 68—70 
must-complete functions, 45 
must-complete sections, 32-33 


mutual exclusion (mutex) semaphore functions: 


DosCloseMutexSem, 314-15 
DosCreateMutexSem, 315-16 
DosOpenMutexSem, 316-18 
DosQueryMutexSem, 318-19 
DosReleaseMutexSem, 319-20 
DosRequestMutexSem, 320 
mutual exclusion (mutex) semaphores, 303-4 
muxwait semaphore functions: 
DosAddMuxWaitSem, 322-23 
DosCloseMuxWaitSem, 323-24 
DosCreateMuxWaitSem, 325-27 
DosDeleteMuxWaitSem, 327 
DosOpenMuxWaitSem, 328-30 
DosQueryMuxWaitSem, 330 
DosWaitMuxWaitSem, 331 
muxwait semaphores, 304 
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national language structures, 213 


National Language Support (NLS), 201-14 
nested exceptions, 35 


P 


PIB structure, 283 
pipe functions: 
named, 233-54 
DosConnectNPipe, 234-35 
DosCreateNPipe, 235-39 
DosDisConnectNPipe, 239-40 
DosPeekNPipe, 240 
DosQueryNPHsState, 242-44 
DosQueryNPipelnfo, 244-45 
DosQueryNPipeSemState, 245-46 
DosResetBuffer, 247 
DosSetNPHState, 247-49 
DosSetNPipeSem, 249-51 
DosTransactNPipe, 251-52 
DosWaitNPipe, 253-54 
nonspecific, 220-29 
unnamed, 230-33 
PIPEINFO structure, 254—55 
pipe instances, 217 
pipe names, 216 
pipes, 215-55 
byte vs. message, 218 
DOS clients and, 219 
LAN considerations and, 219 
named, 216 
nonspecific 
DosClose, 220-21 
DosDupHandle, 221-23 
DosOpen, 223 
DosRead, 225 
DosWrite, 227-29 
redirecting the standard input and standard 
output of a child process with, 215-16 
synchronization of, 219 
transaction processing and remote procedure 
calling with, 218 
unnamed, 215 
DosCalINPipe, 231-33 
DosCreatePipe, 230-31 
PIPESEMSTATE structure, 255 
pipes structures, 254-55 
processes, 256-57 
process level functions, 258-70 
DosEnterCritSec, 258-59 
DosExecPgm, 259-63 
DosExitCritSec, 263-64 
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DosExitList, 264—67 
DosKillProcess, 267-68 
DosWaitChild, 269 
process/thread functions, 277-83 
DosExit, 277-78 
DosGetInfoBlocks, 278—79 
DosSetPriority, 280-83 
process/thread structures, 283-85 
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question mark (?), as metacharacter, 61 
queue functions: 
DosCloseQueue, 288 
DosCreateQueue, 291 
DosOpenQueue, 299-300 
DosPeekQueue, 293-96 
DosPurgeQueue, 296 
DosQueryQueue, 289, 300 
DosReadQueue, 296-99 
DosWriteQueue, 290 
queues, 286-301 
example of queue management, 287 
queue structures, 301 


R 

raising exceptions, 34 

REEQUESTDATA structure, 301 

resource management functions, dynamic, 21-26 


resource types, 23 
RESULTCODES structure, 283-84 


Ss 


semaphore functions, see event semaphore func- 
tions; mutual exclusion semaphore func- 
tions; muxwait semaphore functions 
semaphores: 
event, 302-3 
mutual exclusion (mutex), 303-4 
muxwait, 304 
semaphore structures, 334 
SEMRECORD structure, 334 
session management, 335-52 
session management functions: 
DosSelectSession, 337 
DosSetSession, 338-40 
DosStartSession, 340—44 
DosStopSession, 344 
session management structures, 346-52 
shared memory, 160 


shared memory functions, 172-80 
DosAllocSharedMem, 172 
DosGetNamedSharedMem, 1775-77 
DosGetSharedMem, 177-78 
DosGiveSharedMem, 1778-80 

signal exception functions, 42 

signal exceptions, 33-34 

standard extended attributes (SEAs), 140 

STARDATA structure, 347-52 

STATUSDATA structure, 346-47 

suballocation (heap management) functions, 

180-86 
DosSubAllocMem, 180-82 
DosSubFreeMem, 182-83 
DosSubSetMem, 183-85 
DosSubUnsetMem, 185-86 


T 


thread level functions, 271-77 
DosCreateThread, 271 
DosKillThread, 273 
DosResumeThread, 274-75 
DosSuspendThread, 275 
DosWaitThread, 276 

thread-local memory, 161-62 

thread-local memory functions, 186 
DosAllocThreadLocalMemory, 186-87 
DosFreeThreadLocalMemory, 187 

threads, 256—57 

TIB2 structure, 285 

TIB structure, 284 

timer functions, 355—59 
DosAsynchTimer, 355 
DosSleep, 356 
DosStartTimer, 357-58 
DosStopTimer, 358-59 

timers, 353-61 
asynchronous multiple-interval, 354 
asynchronous single-interval, 353-54 
synchronous, 354 


U 
unwinding exceptions, 35 
user-defined exceptions, 34 
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WinStartTimer, 355 
WinWaitEventSem, 303 
WinWaitMuxWaitSem, 305 
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